How to Make Magento 2 Extensions Compatible with Hyvä Theme?

• By Kiwi Commerce
• 29 Oct, 2025
• Hyva Theme

How to Make Magento 2 Extensions Compatible with Hyvä Theme?

Hyvä themes have become increasingly popular among Magento 2 store owners due to their high performance, improved user experience, and simplified customisation.

However, developers often face challenges when integrating third-party extensions with Hyvä. These include refactoring frontend code to replace Magento’s default components, adapting legacy code to Hyvä’s minimal architecture, and ensuring consistent styling and responsiveness across devices.

This guide explains how to make Magento 2 extensions fully compatible with the Hyvä theme.

Prerequisites for Magento 2 Hyvä Theme Compatibility

Before beginning, ensure the following prerequisites are in place:

1. Understanding of Hyvä Architecture – Familiarise yourself with Hyvä’s structure, which uses Tailwind CSS, Alpine.js, and minimal layouts and templates.
2. Magento 2 with Hyvä Installed – Ensure Hyvä is active on your Magento 2 environment. Updating to the latest Magento version is recommended for security and performance.
3. Server Access – SSH access and permissions to make code changes.
4. Access to Extension Source Code – Full access to the extension’s source code is required to modify, refactor, and test.
5. Testing Environment – Set up a staging or testing environment to safely develop and test compatibility without affecting the live site.

Tip: Always back up your site before making any changes to ensure a quick rollback if needed.

 

Steps to Make a Third-Party Module Compatible with Hyvä

Hyvä does not support jQuery or RequireJS, so many third-party extensions require adjustments. Follow these steps to ensure compatibility:

Step 1: Install the Hyvä Compat Module Fallback

Install the fallback repository via Composer:

composer require Hyva-themes/magento2-compat-module-fallback

Step 2: Configure Dependency Injection

Create a di.xml file in etc/frontend/di.xml for your extension:

<type name=”Hyvä\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”>Hyvä_OrigModule</item>

     </item>

   </argument>

 </arguments>

</type>

Step 3: Override Extension Templates

Adjust the templates to match Hyvä’s directory structure:

• Original Module Template:
  VendorName/ModuleName/view/frontend/templates/FileName.phtml
• Compatible Module Template:
  Hyva/VendorNameModuleName/view/frontend/templates/FileName.phtml
• Theme Override:
  app/design/frontend/Vendor/theme/VendorName_ModuleName/templates/FileName.phtml

Step 4: Add the Module to Tailwind Config

Create tailwind.config.js at view/frontend/tailwind/tailwind.config.js with the following content:

module.exports = {

 purge: {

   content: [

     ‘../templates/**/*.phtml’,

   ]

 }

}

Step 5: Add Module Styles to Tailwind CSS

If custom CSS is required for the extension, create tailwind.source.css in view/frontend/tailwind-source.css. Then enable and upgrade the module:

bin/magento module:enable VendorName_ModuleName

bin/magento setup:upgrade

bin/magento cache:clean

Replace VendorName and ModuleName with the actual extension names.

Common Pitfalls and How to Avoid Them

1. CSS/JS Conflicts
   Legacy extension code may override Hyvä’s core styles or scripts, affecting performance. Replace legacy CSS and JavaScript with Tailwind CSS and Alpine.js where possible.
2. Layout Issues
   Directly copying Magento default layouts may break UI elements. Adapt layout files to Hyvä’s minimal structure.
3. Incompatibility with Other Extensions
   Extensions not following Hyvä standards can cause errors. Test extensions together to ensure smooth functionality.
4. Inconsistent User Experience
   Third-party modules may cause responsiveness issues across devices. Test thoroughly on multiple browsers and screen sizes.

Pro Tip: Keep up to date with Hyvä integrations, such as payment gateways or other third-party services, which may improve compatibility and user experience.

Conclusion

Making Magento 2 extensions compatible with the Hyvä theme requires careful planning, template overrides, and adjustments to CSS and JavaScript. By following these steps and adhering to Hyvä’s best practises, developers can ensure extensions work seamlessly with the theme, providing high performance and a consistent user experience across devices.

Take Your Hyvä Store to the Next Level with Kiwicommerce

Kiwicommerce provides expert services for Hyvä theme users, including:

• Hyvä Theme Migration – Move your Magento store to the high-performance Hyvä theme smoothly.
• Hyvä Performance Optimisation – Maximise speed, responsiveness, and overall user experience.
• Ongoing Hyvä Support & Maintenance – Keep your Hyvä store running efficiently with continuous support and updates.

Get in touch with Kiwicommerce today to ensure your Magento 2 store is fully optimised and Hyvä-ready.