Saltar a contenido

Tooling de Importaciones

La notación Vendor_Module:: es parte de primera clase del flujo de MageObsidian Components, no solo una comodidad en tiempo de build. Tres piezas de tooling la vuelven cómoda y segura de usar: autocompletado en el editor, un watcher en vivo de desarrollo y un guard fail-loud.

No configuras nada de esto —lo prepara el build. Esta página explica qué hace para que el comportamiento no te sorprenda.

Autocompletado en el Editor (jsconfig.json)

En cada build (y en vivo durante el desarrollo) el engine escribe un jsconfig.json en la raíz de las fuentes del tema que le enseña al editor a resolver los especificadores Vendor_Module::. Cada especificador se mapea al archivo fuente real al que resuelve, derivado del mismísimo mapa de herencia que usa el build —así que lo que ve el editor siempre coincide con lo que produce el build.

Lo que obtienes en VS Code (con la extensión Vue/Volar) o PhpStorm:

  • Autocompletado de las rutas de import Vendor_Module::.
  • Ir a la definición (Ctrl/Cmd+clic) salta directo al archivo .vue/.js real, incluso cuando vive en otro módulo o en un tema padre.
  • Resuelven tanto la forma completa (Vendor_Module::components/Card) como el atajo (Vendor_Module::Card).
  • Un comodín "*" también apunta los paquetes npm (vue, @heroicons/..., pinia, …) al node_modules del harness de build, para que resuelvan en el editor también.

Importante: El jsconfig.json generado está gestionado por el build —lleva un marcador // Generated by mage-obsidian en la primera línea, está en el git-ignore y se reescribe en cada build. No lo edites. Si ya existe un jsconfig.json escrito a mano (sin el marcador), el build lo deja intacto y te avisa; elimínalo para que el build tome el control.

Consejo: Tras el primer build (o si la resolución se ve desactualizada), ejecuta Restart TS Server en tu editor para que vuelva a leer el jsconfig.json regenerado.

Contenedores y mounts

Cuando el build corre dentro de un contenedor pero editas los archivos en una ruta de host distinta (un bind-mount), las rutas absolutas grabadas en jsconfig.json apuntarían a rutas del contenedor que el editor no puede abrir. Define MAGE_OBSIDIAN_TYPES_PATH_MAP para remapearlas:

1
2
# from=>to[,from2=>to2]; gana el prefijo más largo
MAGE_OBSIDIAN_TYPES_PATH_MAP=/var/www/html/vite=>/home/yo/proyecto/component-modern-frontend/vite,/var/www/html=>/home/yo/proyecto/magento-root

Cuando el build y el editor comparten sistema de archivos, déjalo sin definir —el mapeo identidad es lo correcto.

Watcher en Vivo de Desarrollo

El mapa de herencia se calcula una vez al arrancar el dev server y se cachea. Agregar o eliminar una fuente .vue/.js sería normalmente invisible hasta un reinicio —tanto para el resolver de runtime como para el jsconfig.json del editor.

Un watcher solo de desarrollo lo soluciona. Cuando creas o eliminas un componente o fuente JS bajo un directorio vigilado (el dir web de cada módulo adherido, más el tema y su cadena de padres), este:

  1. Invalida el mapa de herencia cacheado del tema.
  2. Reescribe el mapa de resolución persistido (para que Vendor_Module:: resuelva el archivo nuevo en runtime).
  3. Regenera el jsconfig.json del tema (para que el editor también lo vea).

Registra sources changed — refreshed <theme> import resolution. Los cambios tienen debounce y las escrituras son idempotentes, así que editar el contenido de un archivo (a diferencia de agregar/eliminar archivos) no lo dispara —de eso se encarga el HMR propio de Vite.

Guard Fail-Loud

Un especificador Vendor_Module:: que no resolvía antes era externalizado en silencio por el bundler, solo para romperse en runtime sin causa clara. Ahora un guard corre el último en la cadena de resolvers: si un especificador :: llega hasta él, ninguno de los resolvers reales pudo manejarlo —un typo o un archivo faltante— así que lanza un error de build/dev en su lugar.

El error nombra el especificador no resuelto, el importador y las alternativas válidas más cercanas:

1
2
3
4
5
[mage-obsidian] Unresolved import "Acme_Catalog::ProductsCard".
  imported by: .../components/Page.vue
  Did you mean:
    - Acme_Catalog::ProductCard
    - Acme_Catalog::products/Card

Para una ruta de asset, te dice exactamente dónde se esperaba el archivo:

1
2
3
4
[mage-obsidian] Unresolved import "Acme_Catalog::assets/logo.svg".
  imported by: .../components/Header.vue
  Asset not found. Expected a theme override at <theme>/Acme_Catalog/web/assets/logo.svg
  or the module at <module>/view/frontend/web/assets/logo.svg.

Y cuando no hay nada registrado bajo el namespace, te recuerda habilitar el módulo/tema y regenerar el contrato:

1
2
  Nothing is registered under "Acme_Catalog". Is the module/theme enabled and
  compatible, and the contract regenerated (bin/magento mage-obsidian:frontend:config --generate)?

Notas Clave

  • El jsconfig.json es generado, está en el git-ignore y no debe editarse a mano.
  • Usa Restart TS Server tras el primer build para activar el autocompletado.
  • Un import :: roto rompe el build con sugerencias —nunca se publica en silencio.
  • El watcher de desarrollo mantiene sincronizados el autocompletado y la resolución de runtime a medida que agregas/eliminas archivos, sin reinicios.