De 3.x a 4.0¶

La actualización toca solo paquetes mage-obsidian/*. Se probó el 2026-10-06 contra una tienda real en 3.x: composer update 'mage-obsidian/*' --dry-run informó 23 actualizaciones, todas de paquetes mage-obsidian/*, y ningún otro paquete cambió.

Antes de empezar¶

Haz un respaldo y lista las constraints mage-obsidian/* del composer.json raíz. composer show 'mage-obsidian/*' --self no las lista; usa esto:

jq '.require | with_entries(select(.key|startswith("mage-obsidian/")))' composer.json

1. Sube todas las constraints de MageObsidian¶

Pasa a composer require --no-update exactamente los paquetes que listó la salida de jq, cada uno como :^4.0. No añadas un paquete que tu composer.json no requiera ya; si queda uno atrás, Composer informa un conflicto.

Para una tienda cuya raíz requiere theme-default y component-modern-frontend:

composer require --no-update mage-obsidian/theme-default:^4.0 mage-obsidian/component-modern-frontend:^4.0

Una tienda que además lista, por ejemplo, module-search, theme-base o module-modern-frontend-cli añade cada uno de la misma forma.

2. Actualiza solo los paquetes de MageObsidian¶

composer update 'mage-obsidian/*'

Warning

No uses -W/--with-all-dependencies: también actualizaría paquetes de tu tienda que no tienen relación, y 4.0 no lo necesita.

3. Temas hijos publicados como paquete propio¶

Publica primero una versión del tema hijo con una constraint mage-obsidian/theme-default:^4.0. Después actualiza ambos juntos:

composer update 'mage-obsidian/*' vendor/child-theme

4. Despliega como de costumbre¶

bin/magento setup:upgrade

Desde el directorio vite/, compila tu tema:

pnpm build:theme <Vendor/theme>

Luego despliega el contenido estático y vacía la caché:

bin/magento setup:static-content:deploy
bin/magento cache:flush

El motor de compilación¶

component-modern-frontend 4.0.0 todavía instala el motor de compilación mage-obsidian 3.2.x, funcionalmente idéntico al motor 4.0.0. A fecha 2026-10-06 no existe component-modern-frontend 4.0.1: subir su pin a ^4.0 es el siguiente parche del framework. Cuando salga, lo único que debes hacer es ejecutar composer update 'mage-obsidian/*' y pnpm install.

La línea 3.x¶

3.x está congelada. Un hotfix de emergencia se publica solo desde una rama 3.x del repositorio afectado. Consulta Versiones y soporte para la política completa.

Solución de problemas¶

Pregunta a Composer por qué un paquete no llega a 4.0.0:

composer why-not mage-obsidian/theme-default 4.0.0

El conflicto típico es una constraint mage-obsidian/* que quedó en ^3 en tu composer.json raíz o en un tema hijo. Súbela como en el paso 1.

Si una tienda fijó los paquetes del storefront exactamente en 4.0.0, las páginas responden HTTP 500 en PHP 8.3/8.4 o Magento 2.4.7. Storefront 4.0.1 (2026-10-06) lo corrige: permite ^4.0 y ejecuta composer update 'mage-obsidian/*'.