From 3.x to 4.0¶

The upgrade touches only mage-obsidian/* packages. It was tested on 2026-10-06 against a real 3.x store: composer update 'mage-obsidian/*' --dry-run reported 23 updates, all of them mage-obsidian/* packages, and no other package changed.

Before you start¶

Take a backup, then list the mage-obsidian/* constraints of your root composer.json. composer show 'mage-obsidian/*' --self does not list them; use this instead:

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

1. Raise every MageObsidian constraint¶

Pass to composer require --no-update exactly the packages the jq output listed, each as :^4.0. Do not add a package your composer.json does not already require; any one left behind makes Composer report a conflict.

For a store whose root requires theme-default and component-modern-frontend:

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

A store that also lists, for example, module-search, theme-base or module-modern-frontend-cli adds each of them the same way.

2. Update only the MageObsidian packages¶

composer update 'mage-obsidian/*'

Warning

Do not use -W/--with-all-dependencies: it would also upgrade unrelated packages of your store, and 4.0 does not need it.

3. Child themes published as their own package¶

Release the child theme first, with a constraint on mage-obsidian/theme-default:^4.0. Then update both together:

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

4. Deploy as usual¶

bin/magento setup:upgrade

From the vite/ directory, build your theme:

pnpm build:theme <Vendor/theme>

Then deploy the static content and flush the cache:

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

The build engine¶

component-modern-frontend 4.0.0 still installs the mage-obsidian build engine 3.2.x, which is functionally identical to the 4.0.0 engine. As of 2026-10-06 there is no component-modern-frontend 4.0.1: raising its pin to ^4.0 is the next framework patch release. Nothing needs to be done on your side when it ships beyond running composer update 'mage-obsidian/*' and pnpm install.

The 3.x line¶

3.x is frozen. An emergency hotfix is published only from a 3.x branch of the affected repository. See Versioning & support for the full policy.

Troubleshooting¶

Ask Composer why a package cannot reach 4.0.0:

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

The typical conflict is a mage-obsidian/* constraint left on ^3 in your root composer.json or in a child theme. Raise it as in step 1.

If a store pinned the storefront packages to exactly 4.0.0, storefront pages answer HTTP 500 on PHP 8.3/8.4 or Magento 2.4.7. Storefront 4.0.1 (2026-10-06) fixes it: allow ^4.0 and run composer update 'mage-obsidian/*'.