What is a Hyvä compatibility module and when do I need one?

A Hyvä compatibility module is a small companion Magento 2 module. It rebuilds a third-party extension’s storefront code so it runs on the Hyvä theme. You need one when an extension renders storefront UI with RequireJS or KnockoutJS and the vendor ships no Hyvä version. Backend and admin-only extensions usually work without one.

How a Hyvä compatibility module works

Hyvä replaces the frontend stack of Luma, Magento 2’s default theme. Luma extensions typically ship RequireJS configs, KnockoutJS templates, jQuery widgets, and LESS styles. None of these load on a Hyvä storefront, which uses only Alpine.js and Tailwind CSS.

The compat module sits beside the original extension and overrides only what touches the storefront: templates, layout XML, and JavaScript. The original module still handles models, observers, configuration, and API calls. Hyvä’s compatibility module documentation describes it as a re-implementation of whatever parts don’t work on Hyvä out of the box.

Shared compat modules follow a naming pattern. The module for Smile ElasticSuite, for example, is Hyva_SmileElasticSuite, published under the hyva-themes Composer namespace. The hyva-themes/magento2-compat-module-fallback package checks the compat module for each template before falling back to the original. A Luma store view on the same install keeps the original templates.

When you need a Hyvä compatibility module

Whether an extension needs a Hyvä compatibility module depends on what it does on the storefront:

Checkout needs extra attention. Hyvä Checkout is a separate product built on Magewire. A payment extension can need support for both Hyvä Checkout and Hyvä Theme. Stay on the Luma checkout fallback, hyva-themes/magento2-luma-checkout, and Luma-based checkout extensions keep working as before.

When an extension doesn’t need a Hyvä compatibility module

Admin-only extensions and backend integrations such as ERP connectors never render on the storefront, so they need no compat module. Extensions whose vendor already ships Hyvä support need no separate build either. Look for a separate Composer package with “hyva” in its name, which Hyvä’s naming conventions recommend for vendor-hosted compat modules. Hyvä’s Compatibility Module Tracker also lists extensions that work on Hyvä natively.

How to check if a Magento extension is Hyvä compatible

The Hyvä Theme itself has been free and open source since November 10, 2025, under OSL 3.0 and AFL 3.0. a free key from your hyva.io account also gives Composer access to third-party compatibility modules. Individual accounts get up to 5 free keys, and agency partner groups up to 50.

Vendor-built compat modules vary in price. Some vendors include them free with an active extension license, while others sell them as paid add-ons.

Run these four checks on each frontend extension:

1. Check the vendor’s documentation: look for a Hyvä section or a separate Hyvä Composer package on the extension’s install page.
2. Search Hyvä’s Compatibility Module Tracker: the tracker shows which compat modules are published and which extensions already work natively.
3. Inspect the extension’s frontend files: run this from your Magento root.

   find vendor/vendor-name/module-name/view/frontend \( -name "requirejs-config.js" -o -path "*/web/template/*.html" \)

   Copy Code
   Any result means the extension uses Luma JavaScript on the storefront. No view/frontend folder at all usually means it runs backend only.
4. Test on staging: switch a store view to Hyvä and check the browser console for require is not defined errors.

To scan a whole store at once, the community-built Hyvä Compatibility Checker lists the modules that need Hyvä compatibility. It’s a Node.js tool you clone into your Magento root. It writes JSON and CSV reports to a hyva-compatibility-analysis folder.

git clone https://github.com/rossmc/hyva-compatibility-checker.git
npm --prefix hyva-compatibility-checker install
npm --prefix hyva-compatibility-checker start

Audit every frontend-facing extension before the Hyvä build starts. Some stores have native support or a published Hyvä compatibility module for each one. For them, the extension work is mostly install and test. Every extension without one adds custom development, so count them early.

Our Hyvä theme development team can review your extension list and scope any compat modules you’ll need.