Third-party Magento 2 extensions break on Hyva because their storefronts ship Knockout, jQuery, and RequireJS that Hyva does not load. Only the frontend breaks; backend logic keeps working. Fixes fall into five paths: native compatibility, a vendor or community compatibility module, a self-built compatibility module, Hyva’s Luma theme fallback, or replacing the extension outright.
Every article on this subject repeats the same handful of sentences: Hyva drops jQuery and Knockout, so you need a compatibility module, check the tracker. All true, and all surface level. What follows goes to the layer underneath: the exact override mechanism, the naming rules, the GraphQL data path, the fallback escape hatch, and a real triage framework for deciding what to do with each extension. It is written from the daily practice of Bemeir, the USA’s first Hyva Gold Partner.
Why Luma extensions break on Hyva
To fix the problem you have to be precise about what actually breaks, because “the extension does not work” is misleading. Most of the extension works fine.
Hyva replaces Magento’s Luma frontend runtime. It does not load RequireJS (the module loader), Knockout.js (the data-binding layer), jQuery, or the Magento UI Components system. In their place it uses Alpine.js and Tailwind CSS. So the part of an extension that fails is narrow and specific: its storefront .phtml templates that emit Knockout bindings, its jQuery widgets, its RequireJS module graph, and its LESS styling. None of that runs on Hyva.
Everything else keeps working, and this is the crucial point. The extension’s dependency injection, PHP business logic, admin panel, resource models, plugins, and observers are all unaffected, because they never touched the frontend runtime. That is why compatibility work is a frontend-only exercise. You are not rebuilding the extension; you are re-skinning its output. This is a detail that matters throughout any serious Magento and Adobe Commerce development engagement, because it scopes the work down dramatically.
What a compatibility module is, and how the override actually works
A Hyva compatibility module is a small module that supplies Hyva-native frontend files for a third-party extension while leaving that extension’s backend alone. The mechanism behind it is more elegant than most write-ups admit.
Compatibility modules build on the hyva-themes/magento2-compat-module-fallback package. Your compatibility module registers itself with Hyva’s compatibility-module registry through dependency injection in etc/frontend/di.xml. Once registered, the module’s view/frontend/templates directory is injected automatically into Magento’s design fallback path. You do not write layout XML to swap templates; if your compatibility module ships a template with the same path as the original, it transparently takes over. Hyva’s technical deep dive on compatibility modules documents this registry and fallback injection in full.
There is a subtle gotcha that trips up teams doing theme-level customization. If you later want to override a compatibility template from within your theme, you must reference the original module’s namespace, not the compatibility module’s, because the automatic fallback does not change the template’s declared module context. Get this wrong and your theme override silently does nothing.
Tailwind assets follow the same merge-in approach: the compatibility module contributes its own Tailwind sources so its utility classes are included when the theme’s stylesheet compiles.
The naming convention nobody documents
Hyva has firm naming rules for compatibility modules, and following them keeps your codebase legible to anyone who knows Hyva. Per Hyva’s compatibility-module development guidelines, the Magento module name is the Hyva namespace plus the original module’s namespace and name, so Smile_ElasticSuite becomes Hyva_SmileElasticSuite. The Composer package always uses the hyva-themes vendor and the pattern hyva-themes/magento2-<original-module>, so smile/magento-elasticsuite becomes hyva-themes/magento2-smile-elasticsuite. If you host the module yourself outside Hyva’s GitLab, use your own vendor name but keep hyva in the package name so its purpose is obvious.
Finding a fix before you build one
The cheapest compatibility work is the work you do not do. Before writing anything, check whether the problem is already solved.
Hyva maintains a public compatibility module tracker on GitLab where modules move through statuses from requested to accepted to published to compatible. A module marked “compatible” works natively and needs nothing from you. Community voting prioritizes what gets built next, so if your extension is not covered yet, adding your vote is worthwhile.
Beyond the tracker, many extension vendors now ship their own Hyva compatibility packages. Bemeir’s network of technology partners across the Magento ecosystem increasingly maintains these directly, which means the vendor owns updates and support rather than your team. Installing a maintained vendor package is almost always better than writing your own, because it survives the next extension upgrade without your intervention.
Writing your own compatibility module
When an extension is business-critical and no compatibility module exists, you build one. The workflow is methodical and done one template at a time.
- Compare the extension’s Luma rendering against its broken Hyva rendering to locate exactly which templates fail.
- Copy the failing template into your compatibility module’s
view/frontend/templates. - Convert its JavaScript: Knockout view models and jQuery widgets become Alpine components, and RequireJS module definitions are dropped in favor of small plain scripts, since Hyva does not use an AMD loader.
- Restyle with Tailwind utility classes in place of the extension’s LESS.
- Add the PHPDoc block Hyva’s coding standard expects at the top of each template, declaring the block and view-model types.
- Test and refine that one template before moving to the next.
There is no automatic converter from Knockout to Alpine. Each interactive widget is read, understood, and rewritten. The effort scales with the number of templates and the complexity of their client-side behavior, which is why an extension with one simple frontend block is a quick job and a checkout or configurator extension is not.
The data layer: GraphQL and dynamic content
Extensions that fetch or mutate data on the client need attention beyond templates. Hyva ships a GraphQL view model, hyva-themes/magento2-graphql-view-model, that lets you adjust queries and mutations before they render. Customization hooks into an event system prefixed hyva_graphql_render_before_, so you can alter, for example, a product-list query without editing core files.
Hyva also supports both a PHP-rendered cart and a GraphQL cart, selectable through layout handles and store configuration flags. When you adapt an extension that reads cart state, you need to know which cart model the store runs, because the same extension behaves differently against a server-rendered cart than against a GraphQL one.
The escape hatch: Luma theme fallback
Sometimes porting a page is not worth it. A heavy legacy configurator, a rarely visited account page, or a complex integration you plan to replace anyway may cost more to adapt than it returns. For these, Hyva provides a genuine escape hatch that most articles conflate with compatibility modules but which is a different tool entirely.
The hyva-themes/magento2-theme-fallback package renders specific routes with a Luma-based theme instead of Hyva. Documented in Hyva’s Luma theme fallback guide, it adds a controller plugin that matches requests by route, controller, and action, or by a fragment of the URL. On a match, it disables Alpine and Tailwind for that page and loads the standard Luma stack. You configure it in the admin under the Hyva fallback settings, pointing matched routes at a Luma theme path. The tradeoff is explicit: the matched page loses Hyva’s performance, but the rest of the store stays fast, and you avoid an expensive port for a page that does not deserve it.
Checkout is a separate problem
Do not assume checkout extensions follow the same rules. Hyva Checkout is built from scratch on Magewire, Alpine, and Tailwind, not on Luma checkout. Standard payment and shipping integrations do not work out of the box; each typically needs its own dedicated Hyva Checkout integration module, maintained by the Hyva team, the payment provider, or the community. One-step-checkout extensions are a special case: they cannot coexist with Hyva Checkout because both try to own the entire checkout flow, so you replace rather than adapt. For a store with significant B2B checkout requirements, our guide to Adobe Commerce B2B on Hyva covers which features carry over and which need a rebuild.
The five-path decision framework
For any given extension, work down this list from cheapest to most expensive and stop at the first path that fits.
| Path | When to use | Who maintains it | Relative effort | Performance |
|---|---|---|---|---|
| Native compatibility | Backend-only or already marked compatible on the tracker | You, nothing to do | None | Full Hyva speed |
| Vendor compatibility module | The vendor publishes one | The vendor | Install and configure | Full Hyva speed |
| Community compatibility module | Tracker shows a published community module | The community | Install and QA | Full Hyva speed |
| Self-built compatibility module | Critical extension, no compat exists | You | Per-template port | Full Hyva speed |
| Luma theme fallback | Porting is uneconomical for that page | You, config only | Configuration only | Loses Hyva on that route |
If none of these fit, two final options remain: replace the extension with a Hyva-native alternative, sensible when the current one is unmaintained or its whole frontend needs rebuilding anyway, or drop it entirely if it is low value and blocking your migration. Hyva’s own documentation describes compatibility work as mostly straightforward and done one template at a time, but no reliable public source puts hour or dollar figures on it, so scope each extension on its own rather than trusting a blanket estimate.
A note on platform choice
This entire class of problem is specific to Magento’s frontend architecture. Merchants on Shopify or Shopify Plus, Shopware, or BigCommerce work with different app and theme models and do not face Hyva compatibility questions at all. That is not an argument to leave Magento; it is context. Magento’s extension depth is a genuine strength, and Hyva compatibility work is the price of keeping that depth while gaining front-end speed. Handled with the framework above, it is a manageable, one-time cost, and Bemeir’s Hyva development practice exists to make it routine.
Frequently asked questions
Do an extension’s admin or backend features break on Hyva?
No. Only the Luma storefront frontend breaks, meaning its .phtml templates, jQuery, RequireJS, and Knockout code. The extension’s PHP business logic, admin panel, data layer, plugins, and observers all run unchanged, which is why compatibility work is frontend-only.
How do I tell if an extension already works with Hyva?
Check the Hyva compatibility module tracker on GitLab. A module in the “compatible” column works natively and needs no compatibility module. If it is not listed or not yet compatible, look for a vendor or community compatibility package before planning to build your own.
What is the naming convention for a compatibility module?
The Magento module is named Hyva_<VendorModule>, for example Hyva_SmileElasticSuite, and the Composer package is hyva-themes/magento2-<original-module>. If you host it outside Hyva’s GitLab, use your own vendor name but keep hyva in the package name so its purpose stays clear.
Can I keep a page on Luma instead of porting it?
Yes. The hyva-themes/magento2-theme-fallback package routes specific controllers or URLs to a Luma theme, disabling Alpine and Tailwind for just those pages. It is the right choice when porting a complex or low-traffic page costs more than it returns, at the cost of Hyva performance on that route.
Why will my payment or one-step-checkout extension not work with Hyva Checkout?
Hyva Checkout is rebuilt on Magewire and Alpine, so payment and shipping integrations need dedicated Hyva Checkout integration modules rather than their Luma versions. Full one-step-checkout extensions must be replaced, not adapted, because they conflict with Hyva Checkout’s own control of the flow.
