How to check (and fix) Hyvä compatibility for a Magento extension

A Magento 2 extension is Hyvä compatible when its frontend works without Luma's JavaScript stack, either because the vendor ships Hyvä templates or because a compatibility module re-implements the parts that break.¹ To check, ask the vendor, search the Hyvä Compatibility Module Tracker, look inside the module for RequireJS and Knockout code, and test it on a Hyvä staging store with the browser console open. If it is not compatible, you can use an existing compatibility module, route specific pages to a Luma theme with the theme fallback module, or write your own compatibility module.

Why do Luma extensions break on Hyvä?

Luma storefronts load RequireJS, Knockout and jQuery. Hyvä replaces that stack with Tailwind CSS and Alpine.js, and Hyvä's own checkout documentation puts the difference plainly: on a Luma fallback route, Magento loads "the standard Luma CSS and JavaScript (RequireJS, Knockout, jQuery) instead of Tailwind CSS and Alpine.js".² Hyvä also states that it does not use Knockout.js, so customer section data is not made of Knockout observables.³

A typical Luma extension initialises its JavaScript through a data-mage-init attribute or a <script type="text/x-magento-init"> tag, both of which hand a component to RequireJS.⁴ Modules declare their RequireJS paths, maps and mixins in a requirejs-config.js file.⁵ On a Hyvä page none of this is loaded, so the markup may render but the behaviour does not, and the styling written in Luma's LESS does not match a Tailwind theme.

How do you check whether an extension is Hyvä compatible?

Work through these checks in order. The first two take minutes; the last one is the only proof.

A quick search over the installed module shows how much Luma-specific frontend code it carries:

cd vendor/<vendor>/<module>
find . -path '*view/frontend*' -name 'requirejs-config.js'
grep -rlE 'data-mage-init|x-magento-init' --include='*.phtml' .
grep -rl 'hyva_' --include='*.xml' view/frontend/layout 2>/dev/null

Finding RequireJS code does not mean the extension fails on Hyvä. A module can ship both: Hyvä's guidance for making an existing module compatible is that its phtml, CSS and JavaScript work with both themes, with Hyvä-only logic loaded through hyva_ layout files that Luma ignores.⁶ That is why the staging test matters.

For the test, Hyvä recommends keeping a second store view on Luma as a reference. Open the page that uses the extension in a private window on the Luma view, open the same page on the Hyvä view, and look for errors in the browser console.⁷⁶ Then click through every feature the extension adds, logged in and logged out.

What are your options when an extension is not compatible?

1. The vendor provides Hyvä support

This is the simplest outcome: Hyvä templates either ship inside the extension or come as a separate compatibility package from the vendor. You install it like any other Composer package and keep one supplier responsible for both themes. Our own extensions are built this way: each one ships Luma and Hyvä templates, and the Hyvä section of our catalogue lists them.

2. An existing Hyvä compatibility module

Compatibility modules are separate modules that re-implement the parts of an extension that do not work on a Hyvä storefront.¹ Modules built through Hyvä's process live in the Hyvä Compat group on gitlab.hyva.io and are published under package names such as hyva-themes/magento2-<module>; once a module is tagged 1.0.0 it can be installed with Composer from Hyvä's Packagist.⁶ Hyvä's Theme page lists access to third-party compatibility modules via the free licence key.⁸ Check the tracker before you start writing your own.

3. The Luma theme fallback for specific pages

The hyva-themes/magento2-theme-fallback module routes configured URLs to a Luma-based theme while the rest of the store stays on Hyvä. On those pages Tailwind CSS and Alpine.js are not loaded; RequireJS and the Luma dependencies are, and any styling has to be done the standard Magento way.⁹ You configure it in the admin under the Hyvä Themes menu, with a theme path (default frontend/Magento/luma) and a list of URL parts.⁹¹⁰

The checkout is the most common use.⁹ The hyva-themes/magento2-luma-checkout convenience module depends on the fallback module and configures it for the Luma checkout; Hyvä notes that any checkout built for Luma or Blank can work this way, but needs extra styling to match the Hyvä storefront.²

4. Your own compatibility module

Hyvä's naming convention is the Hyva namespace plus the original vendor and module name, so Smile_ElasticSuite becomes Hyva_SmileElasticSuite.⁷ The module registers itself in etc/frontend/di.xml:¹¹

<type name="Hyva\CompatModuleFallback\Model\CompatModuleRegistry">
    <arguments>
        <argument name="compatModules" xsi:type="array">
            <item name="orig_module_map" xsi:type="array">
                <item name="original_module" xsi:type="string">Orig_Module</item>
                <item name="compat_module" xsi:type="string">Hyva_OrigModule</item>
            </item>
        </argument>
    </arguments>
</type>

Once registered, a template at the same path in the compat module's view/frontend/templates replaces the original without extra layout XML (price renderer templates are the exception and need layout XML).¹¹ Compat modules registered this way are also picked up automatically for Tailwind compilation.¹¹

Hyvä's workflow is to fix one template at a time: copy the template that triggers the error, inline its JavaScript, convert it to vanilla JavaScript and Alpine.js, and style it with Tailwind CSS.⁷ Dependencies on jQuery can usually be replaced with native JavaScript.¹² A Knockout binding that toggles a class becomes a few Alpine attributes, as in this example from Hyvä's docs:⁴

<div x-data="{ isSelected: true }">
    <input type="checkbox" id="<?= $escapedId ?>" value="1" x-model="isSelected">
    <img src="<?= $field->getMediaUrl() ?>" :class="{ 'opacity-40': isSelected}">
</div>

Larger scripts go into a named function registered with Alpine.data inside an inline <script> in the template.¹² If you need this done for a store, it is the kind of work we take on as custom Magento development.

Hyvä Checkout or the Luma checkout fallback?

Hyvä recommends Hyvä Checkout as the checkout built for Hyvä themes, without the overhead of loading the Luma frontend stack.² The Luma fallback is the route when you have to keep a Luma-based checkout during a migration or for compatibility reasons.² Payment extensions are the point to check: Hyvä's payment documentation contrasts Luma's Knockout-based payment approach with Hyvä Checkout's server-side Magewire approach, so ask whether a payment module supports Hyvä Checkout itself, not only the Luma checkout.¹³

How should you test after installing a fix?

• Repeat the side-by-side check against the Luma reference store view and keep the console free of errors.⁷
• Test as a guest and as a logged-in customer, on desktop and mobile widths.
• For fallback routes, check that the page switches theme where you expect and that navigation back to Hyvä pages works.
• Rebuild the Tailwind CSS of your theme so new classes from compat module templates are included.¹¹
• In production mode, deploy static content after enabling the Luma checkout fallback.²

What should you ask an extension vendor?

• Do Hyvä templates ship in the extension, or in a separate package, and which package name?
• Which Hyvä Theme versions, and does it support Hyvä Checkout or only the Luma checkout fallback?
• Does any frontend feature still rely on RequireJS, Knockout or jQuery on a Hyvä store?
• Is the Hyvä version tested and released alongside each Luma release?

Is Hyvä still a paid theme?

No. Hyvä now describes Hyvä Theme as "entirely Open Source and Free", available on GitHub and through free licence keys under the OSL and AFL licences.⁸ The theme repository states it is dual-licensed under OSL 3.0 and AFL 3.0.¹⁴ Hyvä's commercial licence terms still cover Hyvä UI, Hyvä Checkout, Hyvä Commerce and Hyvä Enterprise, and refer to Hyvä Theme licences bought before 10 November 2025.¹⁵ For how the two frontends compare, see Hyvä vs Luma.

Frequently asked questions

Can I run a Luma extension on a Hyvä store without changes?

Only if its storefront output does not rely on RequireJS, Knockout or jQuery. Test it on a Hyvä staging store before you go live.

Where do I find existing Hyvä compatibility modules?

In the Compatibility Module Tracker on gitlab.hyva.io, which lists available modules and their status.¹

What changes on pages that use the Luma theme fallback?

Only the configured routes change. On those pages the browser loads RequireJS and the Luma dependencies instead of Tailwind CSS and Alpine.js.⁹

Can one module support Luma and Hyvä at the same time?

Yes. Hyvä's guidance is to keep templates, CSS and JavaScript compatible with both, and to put Hyvä-only logic in hyva_ layout files that Luma ignores.⁶

What does require is not defined in the console mean?

A script on the page expects RequireJS, which Hyvä does not load. Hyvä's docs use this error as the starting point for finding the template to convert.⁷

What to do next

List every extension with frontend output on your store and run the checks above on each one, starting with checkout, payment and account features. Ask vendors the questions in this article before you buy, and check the tracker before writing a compat module. If you need Hyvä templates for a module of your own, contact us about custom Magento work.

Sources

1. Hyvä Docs, "Compatibility Modules: Overview", https://docs.hyva.io/hyva-themes/compatibility-modules/index.html, checked 8 October 2026. ↩1 ↩2 ↩3 ↩4
2. Hyvä Docs, "Luma Checkout with Hyva Themes", https://docs.hyva.io/hyva-checkout/faq/luma-checkout-faq.html, checked 8 October 2026. ↩1 ↩2 ↩3 ↩4 ↩5
3. Hyvä Docs, "Hyvä JavaScript events", https://docs.hyva.io/hyva-themes/writing-code/hyva-javascript-events.html, checked 8 October 2026. ↩
4. Hyvä Docs, "Visual feedback to user actions", https://docs.hyva.io/hyva-themes/writing-code/patterns/visual-feedback-to-user-actions.html, checked 8 October 2026. ↩1 ↩2
5. Adobe Commerce Frontend Development, "RequireJS in Commerce", https://developer.adobe.com/commerce/frontend-core/javascript/requirejs, checked 8 October 2026. ↩
6. Hyvä Docs, "Compatibility Modules: Getting Started", https://docs.hyva.io/hyva-themes/compatibility-modules/getting-started.html, checked 8 October 2026. ↩1 ↩2 ↩3 ↩4 ↩5
7. Hyvä Docs, "Compatibility Modules: Development Guidelines", https://docs.hyva.io/hyva-themes/compatibility-modules/development-guidelines.html, checked 8 October 2026. ↩1 ↩2 ↩3 ↩4 ↩5 ↩6
8. Hyvä, "Hyvä Theme", https://www.hyva.io/hyva-theme-license.html, checked 8 October 2026. ↩1 ↩2
9. Hyvä Docs, "Luma Theme Fallback", https://docs.hyva.io/hyva-themes/building-your-theme/luma-theme-fallback.html, checked 8 October 2026. ↩1 ↩2 ↩3 ↩4
10. Hyvä Themes on GitHub, "magento2-theme-fallback" README, https://github.com/hyva-themes/magento2-theme-fallback, checked 8 October 2026. ↩
11. Hyvä Docs, "Compatibility Modules: Technical Deep-Dive", https://docs.hyva.io/hyva-themes/compatibility-modules/technical-deep-dive.html, checked 8 October 2026. ↩1 ↩2 ↩3 ↩4
12. Hyvä Docs, "From Luma to Hyvä: Migrating JavaScript and templates", https://docs.hyva.io/hyva-themes/compatibility-modules/from-luma-to-hyva/migrating-js-and-templates.html, checked 8 October 2026. ↩1 ↩2
13. Hyvä Docs, "Payment in Hyvä Checkout", https://docs.hyva.io/hyva-checkout/devdocs/payments/payment-in-hyva-checkout.html, checked 8 October 2026. ↩
14. Hyvä Themes on GitHub, "magento2-default-theme" README, https://github.com/hyva-themes/magento2-default-theme, checked 8 October 2026. ↩
15. Hyvä, "License", https://www.hyva.io/license, checked 8 October 2026. ↩