Saltar a contenido

Generación de Archivos Estáticos

MageObsidian utiliza Vite para procesar y empaquetar los recursos del frontend (CSS, JavaScript, componentes Vue). Esta página cubre cómo generar esos recursos a disco —para inspección local sin HMR, para CI y para el despliegue a producción.

Build de un Tema a Disco (sin HMR)

Para construir un único tema una vez a disco —los mismos artefactos que recibiría un navegador, pero escritos en web/generated en lugar de servidos por el dev server— usa el comando de dev con --no-watch:

1
bin/magento mage-obsidian:frontend:dev --start --no-watch --theme=Vendor/theme

Es el inverso de --start (HMR): sin daemon, sin watch —corre un build y termina. Útil para inspeccionar la salida real o reproducir un build de CI en local.

Salir del ciclo de dev con bin/magento mage-obsidian:frontend:dev --down corre este mismo build por ti (HMR off + rebuild a disco). Usa --no-watch directo cuando solo quieras un build puntual sin tocar HMR.

El bin del engine por debajo

frontend:dev envuelve el bin propio del engine de build, que también puedes correr directamente desde el harness vite/ (es lo que usa CI):

1
2
3
# desde el directorio vite/ del componente
mage-obsidian:build-themes                  # construir todos los temas compatibles
mage-obsidian:build-themes --theme Vendor/theme   # construir uno

frontend:dev es el punto de entrada del lado Magento (primero deriva el .env de Vite desde tu config); build-themes es el comando de bajo nivel del engine. Ambos producen la misma salida.

Corré primero el export del CMS

1
bin/magento mage-obsidian:cms:export
Tailwind escanea archivos y el contenido CMS vive en una base de datos. El export lo vuelca para que el build cubra las clases escritas en páginas y bloques; sin él, esas clases caen al delta de runtime. Ver Contenido CMS.

Despliegue a Producción

Para producción no corres un paso de build aparte. MageObsidian se engancha al deploy de contenido estático estándar de Magento: sus plugins de deploy excluyen los temas modernos del pipeline legacy de Less/RequireJS y producen/inyectan la salida de Vite como parte del comando normal:

1
2
bin/magento deploy:mode:set production
bin/magento setup:static-content:deploy

Los assets generados por Vite quedan en el contenido estático desplegado junto a todo lo demás. Vite se encarga de la minificación, el tree-shaking y el hashing de assets para cache-busting automáticamente.

Solo temas compatibles. Solo los temas que entregan etc/mage_obsidian_compatibility.xml (y han sido detectados por mage-obsidian:frontend:config --generate) pasan por el pipeline de Vite. Los temas sin él siguen el deploy nativo de Magento intacto.

¿Qué tan rápido es?

Los deploys estáticos legacy son famosos por tardar minutos. Como el build de Vite reemplaza todo el pipeline de Less/RequireJS, un tema MageObsidian se despliega en segundos — esta es una corrida real contra un Magento 2.4.8 con sample data, un tema y un locale:

1
2
bin/magento setup:static-content:deploy -f --theme MageObsidian/default en_US
# Execution time: 3.19s — build de producción de Vite incluido (688ms, 753 módulos)

Los números absolutos varían con el hardware y el tamaño del tema, pero la forma se mantiene: el build de Vite está en territorio sub-segundo y domina la materialización de archivos, así que el deploy del tema completo queda en segundos de un dígito.

Requisitos del servidor

Como el build de Vite corre dentro de setup:static-content:deploy, la máquina que ejecute ese comando necesita el toolchain JS de Requisitos —Node ≥ 22 y pnpm ≥ 11— además de PHP. Esto aplica a tu servidor de deploy, imagen de CI o build server, no solo a las máquinas de desarrollo. Si tu pipeline construye el contenido estático en un build host separado, solo ese host necesita Node/pnpm.

Mismatch de versión con corepack. vite/package.json fija la versión exacta de pnpm vía el campo packageManager. Si el servidor tiene corepack habilitado con otro pnpm activo, el build aborta con un error de version-mismatch antes de hacer nada. Se arregla activando la versión fijada:

1
corepack prepare pnpm@11.7.0 --activate

(Ajusta la versión al pin packageManager vigente en vite/package.json.)

Beneficios

  • Salida optimizada — assets minificados, con tree-shaking y hash, listos para producción.
  • Integración nativa — los builds de producción ocurren dentro de setup:static-content:deploy; sin paso extra en tu pipeline de deploy.
  • Coexistencia — los temas legacy siguen usando el deploy estático nativo de Magento; solo los temas modernos usan Vite.

Consulta Flujo de Desarrollo para el dev server con HMR y el conjunto completo de comandos, y HMR para la recarga en vivo durante el desarrollo.