mage-obsidian — JS Build Engine

📚 Documentation · 🚀 Live demo · 💬 Discussions

The JavaScript build engine behind MageObsidian, a modern frontend for Magento 2. ESM-only, consumed by the Vite harness as the mage-obsidian npm package.

What it does

• Theme inheritance resolution — merges module web assets with theme and parent-theme overrides into the final set of JS/Vue/CSS entries, Magento-style.
• Precompilation — generates per-theme precompiled.js / precompiled.css consumed as Vite inputs.
• JS interceptors — a port of Magento's plugin system (before/around/after, sortOrder) implemented as a Vite plugin with virtual modules, so a module can customize another module's JS without patching its source.
• mage-obsidian:build-themes — the CLI that reads the config contract generated by the PHP side and runs vite build / dev server per theme.

Usage

You normally don't install this package directly — it comes with the Vite harness:

composer require mage-obsidian/component-modern-frontend
pnpm --prefix vite install

See the documentation for theme/module configuration (theme.config.js, module.config.ts, interceptors and more).

Development

npm test    # Jest with native ESM

Support the project

If MageObsidian saves you time, consider buying me a coffee. ❤️