Skip to content
Hyvä Theme

Luma Module Not Working in Hyvä: Diagnose the Symptom, Then Choose a Fix

A module that worked on Luma is installed and something on the Hyvä storefront is broken: a missing block, script errors, an inert widget or a missing checkout field. This guide matches the symptom to the failing layer on a staging copy, then compares the realistic fixes: an existing compatibility module, your own compatibility module with Alpine.js and Tailwind, a route-level Luma fallback, or replacing the module.

A grey module marked with a cross swapped for a green compatible module that fits into a store page marked with a check

A module that worked on Luma is installed, and on the Hyvä storefront something is wrong: a block is missing, a widget does nothing, the console fills with script errors, or a checkout field never appears. This guide starts from that visible symptom, finds the layer that is failing, and then walks the realistic fixes.

Not every module can be made to work on Hyvä at a cost that makes sense. Sometimes the right outcome is a Luma fallback for one route, or a different module. The point of the diagnosis is to make that choice with evidence.

If you are still planning the migration and nothing is broken yet, the proactive Hyvä module compatibility check is the better starting point. It covers the tracker lookup, the source review and what a scanner can and cannot tell you.

Diagnose on staging, not on the live store

Reproduce the problem on a staging or local copy with the same code, theme and configuration. That is where you can use developer mode and read var/log and var/report freely. Do not turn on developer mode or visible errors on the public production site, and do not paste logs, reports or stack traces into public tickets or forums.

Why a working Luma module breaks on Hyvä

Hyvä is not built on Luma. A module written for Luma or Blank needs a compatibility module that re-implements the parts that do not work on a Hyvä storefront. The module's PHP, database and admin code usually keep working. What fails is the frontend layer: RequireJS configuration, jQuery widgets, Knockout templates and UI components are not loaded on Hyvä pages, Luma LESS is not compiled, and Hyvä's layout reset removes the block declarations of core Magento modules and bundled extensions, which some third-party layout XML depends on.

Step 1: Match the symptom to a layer

What you seeLikely layerHow to confirm
The block is missing completely, with no markup in the page sourceLayout: the block is attached to a parent that does not exist on Hyvä pagesOn staging in developer mode, Magento logs a "Broken reference" message when an element cannot be added to a missing parent. Search var/log for the block name.
Markup is present but buttons, tabs or forms do nothing, and the console shows a ReferenceError for require, define, jQuery or $JavaScript: RequireJS modules or jQuery widgetsSearch the page source for data-mage-init, x-magento-init and text/x-magento-template. Check the module for requirejs-config.js.
Raw data-bind attributes or <!-- ko --> comments in the source, or an empty area where a component should beKnockout templates and UI componentsLook for view/frontend/web/template/*.html, uiComponent classes and jsLayout arguments in the module's layout XML.
Content appears but looks unstyledStyles: Luma LESS is not compiled, or the Tailwind classes were not included in the theme buildCheck for LESS in view/frontend/web/css, and whether the module is listed in app/etc/hyva-themes.json.
Customer-specific content, such as a mini cart counter or a greeting, is stale or emptyCustomer section dataLook for customerData calls and etc/frontend/sections.xml. Hyvä code reads section data on the private-content-loaded event.
A checkout field, step or payment option is missingCheckout: the module extends the Luma checkoutCheck which checkout the store runs. Mixins and jsLayout changes for Magento_Checkout do not apply to Hyvä Checkout, which is built on Magewire.
Checkout shows "Main wire element could not be found"Configuration: the checkout route is still in the theme fallback listHyvä documents that this happens when checkout/index is still listed in the Theme Fallback settings while Hyvä Checkout is in use.

Take the first error in the console, not the last. Later errors are often caused by the first one. A module can also fail in more than one layer, for example a widget that needs both a layout fix and a JavaScript port.

Step 2: Confirm the cause before changing code

On staging, disable the module and reload the page. If the problem disappears, you have the right module. Then check three things before writing anything:

  • Is a compatibility module already installed? composer show lists installed packages; look for the module's name together with hyva. If one is installed, compare its supported versions with the original module's installed version.
  • Was a template overridden in your theme? A copy under app/design/frontend/<Vendor>/<theme>/<Module_Name>/templates wins over a compatibility module's template.
  • Is the problem only on some store views? Configuration at store scope can switch a feature on in one place and not another.

Fix option 1: Install an existing compatibility module

Search Hyvä's public Compatibility Module Tracker and the extension vendor's documentation. Tracker issues usually name the compatibility module's Composer package and Magento module name, and list which features are covered. Hyvä's own compatibility modules are named like Hyva_SmileElasticSuite for Smile_ElasticSuite, as shown in the development guidelines. Vendor-maintained packages include hyva in their package name.

Install it on a development copy first, run bin/magento setup:upgrade, rebuild the Hyvä theme's Tailwind CSS so the module's classes are included, and retest every page the module touches. From 10 November 2025 Hyvä relicensed the Hyvä Theme and the modules that support it under open source licences. Third-party compatibility packages carry their own licences, so check each one.

Fix option 2: Write your own compatibility module

When nothing exists, write a small module that keeps the original module's PHP and replaces only the frontend parts. Hyvä's hyva-themes/magento2-compat-module-fallback package does the template wiring: once a module is registered as a compatibility module, a .phtml file placed at the same path in the compatibility module overrides the original module's template without any layout XML. Registered modules are also added to app/etc/hyva-themes.json, so their Tailwind classes are picked up by the theme build, as the technical deep-dive describes.

For an original module Panth_Example, a private compatibility module could be Panth_ExampleHyva. Its etc/module.xml loads after both modules it depends on:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Panth_ExampleHyva">
        <sequence>
            <module name="Panth_Example"/>
            <module name="Hyva_CompatModuleFallback"/>
        </sequence>
    </module>
</config>

It registers itself in etc/frontend/di.xml:

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Hyva\CompatModuleFallback\Model\CompatModuleRegistry">
        <arguments>
            <argument name="compatModules" xsi:type="array">
                <item name="panth_example_hyva" xsi:type="array">
                    <item name="original_module" xsi:type="string">Panth_Example</item>
                    <item name="compat_module" xsi:type="string">Panth_ExampleHyva</item>
                </item>
            </argument>
        </arguments>
    </type>
</config>

Then copy the original template to the same path under view/frontend/templates, and rewrite it with inline Alpine.js and Tailwind classes. A Luma toggle that used data-mage-init might become:

<?php
/** @var \Magento\Framework\View\Element\Template $block */
/** @var \Magento\Framework\Escaper $escaper */
/** @var \Hyva\Theme\ViewModel\HyvaCsp $hyvaCsp */
?>
<div x-data="panthExampleToggle" class="my-4 border-t pt-4">
    <button type="button" class="btn" @click="toggle" :aria-expanded="ariaExpanded">
        <?= $escaper->escapeHtml(__('Delivery details')) ?>
    </button>
    <div x-show="open" class="mt-2 text-sm">
        <?= $escaper->escapeHtml($block->getData('details_text')) ?>
    </div>
</div>
<script>
    document.addEventListener('alpine:init', () => {
        Alpine.data('panthExampleToggle', () => ({
            open: false,
            toggle() { this.open = !this.open; },
            ariaExpanded() { return this.open ? 'true' : 'false'; }
        }));
    }, { once: true });
</script>
<?php $hyvaCsp->registerInlineScript() ?>

Hyvä's guide to migrating Luma JavaScript and templates describes the same order: move the RequireJS module's code into a script in the template, replace jQuery and other helper-library calls with native JavaScript, convert x-magento-template blocks to Alpine.js templates, and wait for private-content-loaded when the code needs customer section data. The sample is written to work on both the default and the CSP theme: the Alpine component uses no inline expressions (the aria-expanded value comes from a method), and the inline script is registered with $hyvaCsp->registerInlineScript() right after it, as Hyvä's Alpine CSP guide describes.

When a block has to be added back to a page, use a layout file with the hyva_ prefix, such as hyva_default.xml. Hyvä's getting started guide explains that a Luma theme ignores these files, so they apply only to Hyvä, and the core compatibility module notes use hyva_default.xml to add removed blocks again.

Keep the server side as it is where you can. A controller or REST endpoint that fed a Knockout component can usually feed the new Alpine.js code. Large UI component trees, especially inside the Luma checkout, are where a port becomes a rebuild, and that is the point to compare the cost with options 3 and 4.

Fix option 3: Serve specific routes with a Luma theme

Hyvä's hyva-themes/magento2-theme-fallback module (Hyva_ThemeFallback) lets configured routes use a Luma-based theme instead of Hyvä. It is configured under hyva_theme_fallback/general, and a request matches when an entry in list_part_of_url equals the route path or appears in the URL path. A short entry such as customer/account covers every page below it, so keep entries specific.

For checkout, hyva-themes/magento2-luma-checkout sets this up for the checkout routes. Hyvä's Luma checkout FAQ lists the default Magento checkout and several Luma-based one-step checkouts as usable this way. The trade-offs are documented too: fallback pages load the Luma stack instead of Tailwind CSS and Alpine.js, they need their own styling to match the Hyvä pages, the fallback theme must be Luma or Blank based, and in production mode static content has to be deployed before the fallback works.

This is a reasonable choice for a checkout extension with no Hyvä Checkout integration, or for one or two low-traffic routes. Hyvä Checkout itself remains a commercial product.

Fix option 4: Replace or remove the module

Replace the module when the port would rebuild most of its frontend, when the vendor no longer maintains it, or when a maintained alternative already has a Hyvä compatibility module. Remove it when the store no longer uses the feature. Plan data migration and URL handling before removing a module that owns storefront pages or stored data.

After the fix: deploy and retest

Ship the change through the normal deploy: install or update packages, run setup:upgrade, compile and deploy static content in production mode, and rebuild the Hyvä theme CSS as part of the build. Use bin/magento cache:clean for the affected cache types instead of reaching for cache:flush. Adobe's cache management guide explains that cleaning removes only Commerce's enabled cache types, while flushing purges the cache storage and can affect other applications using the same storage. Then retest the same pages and states from Step 1: guest and logged in, empty and full cart, every store view that uses the module.

Frequently asked questions

Can every Luma extension be made to work on Hyvä?

Not at a reasonable cost in every case. Most modules can get a compatibility module, but some frontends, especially large checkout UI component trees, are closer to a rebuild. A Luma fallback for specific routes or a replacement module is sometimes the better outcome.

The block renders on Luma but not on Hyvä and there is no console error. Where do I look?

Start with layout. On a staging copy in developer mode, Magento logs a "Broken reference" message when a block cannot be added to a missing parent. Re-add the block to a parent that exists on Hyvä pages in a hyva_ prefixed layout file in your compatibility module.

I installed a compatibility module and the problem is still there. Why?

Check that its supported versions match the original module you have installed, that a template override in your own theme is not taking priority, that setup:upgrade ran, and that the theme's Tailwind CSS was rebuilt. Then retest on staging.

Should I use the Luma checkout fallback or port a checkout extension?

The fallback keeps a Luma-based checkout working on the checkout routes, at the cost of loading the Luma stack and styling those pages separately. Porting fits when you run Hyvä Checkout and need the feature there. Compare the effort and how important the feature is before choosing.

Do I need cache:flush after each change?

No. Clean the affected cache types with cache:clean. Flushing empties whole cache storage, which on shared Redis or file storage can affect other applications.

Got a Luma module broken on Hyvä? I diagnose the failing layer on a staging copy, then recommend and build the fix that fits: an existing compatibility module, a custom one, a route-level Luma fallback, or a replacement. Written quote after a short brief.

Get help with a broken module

Tagged #Hyvä #Tailwind #Alpine.js #Extension Compatibility #Magewire

Kishan Savaliya

Written by

Kishan Savaliya

Adobe-certified Magento 2 + Hyvä developer. 60+ open-source extensions published. Founder of Panth Infotech.

Adobe Certified since 2021Hyvä and Luma

All posts by Kishan Savaliya
More in Hyvä Theme
Stuck on this? Share the issue or question Ask about your store