How to Make a Third-party Module Compatible with Hyvä Theme

Why a Module Stops Working in Hyvä

Hyvä Theme does not support jQuery and RequireJS. Many third-party modules rely on these libraries for frontend functionality such as showing/hiding banners, popups, or dynamic updates. For example, a promo bar might have JavaScript behaviors that break when used with Hyvä.

To fix this, we create a Hyvä compatibility extension to replace the frontend files and adapt the module for Hyvä.

Step 1: Install the Compat Module Fallback

First, install the official Hyvä Compat Module Fallback via Composer:

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

This module allows your custom compatibility extensions to override frontend templates and JS files safely.

Step 2: Configure Dependency Injection (DI)

Create a di.xml in etc/frontend/di.xml of your compatibility module:

<type name="Hyva\CompatModuleFallback\Model\CompatModuleRegistry">
  <arguments>
    <argument name="compatModules" xsi:type="array">
      <item name="demo_module_map" xsi:type="array">
        <item name="original_module" xsi:type="string">Mavenbird_Demo</item>
        <item name="compat_module" xsi:type="string">Hyva_MavenbirdDemo</item>
      </item>
    </argument>
  </arguments>
</type>
      

This tells Hyvä to replace the original module’s frontend files with the Hyvä-compatible ones.

Step 3: Override Templates for Hyvä

Directory structure for overriding templates:

• Original module template: Mavenbird/Demo/view/frontend/templates/demo_template.phtml
• Compat module template: Hyva/MavenbirdDemo/view/frontend/templates/demo_template.phtml
• Theme override: app/design/frontend/Vendor/theme/Mavenbird_Demo/templates/demo_template.phtml

Example: If your Mavenbird_Demo module has a dynamic banner or form, this override ensures it works fully in Hyvä.

Step 4: Add Module to Tailwind Purge Config

Tailwind CSS scans your templates for class names to include in the final CSS. Add your compat module templates to tailwind.config.js:

module.exports = {
  purge: {
    content: [
      '../templates/**/*.phtml',
      '../../../Hyva/MavenbirdDemo/view/frontend/templates/**/*.phtml'
    ]
  }
}
      

Step 5: Add Custom CSS (Optional)

If your module requires additional styling, create a Tailwind source file:

view/frontend/tailwind/tailwind-source.css

Example content:

.demo-banner {
  @apply bg-blue-500 text-white p-4 rounded shadow-md;
}
      

Tailwind will compile this CSS along with Hyvä theme styles automatically.

Extra Example: Mavenbird_Demo Booking Form Module

Suppose you have another feature in Mavenbird_Demo handling a demo booking form:

• Original template: Mavenbird/Demo/view/frontend/templates/booking_form.phtml
• Compat module template: Hyva/MavenbirdDemo/view/frontend/templates/booking_form.phtml
• Theme override: app/design/frontend/Vendor/theme/Mavenbird_Demo/templates/booking_form.phtml

This ensures the booking form and dynamic features work perfectly in Hyvä without breaking JS functionality.

Summary

To make any third-party or demo module compatible with Hyvä:

1. Install the Compat Module Fallback.
2. Configure DI with your compat module mapping.
3. Override templates and JS in a compat module.
4. Add your templates to tailwind.config.js for CSS compilation.
5. Add any custom CSS in tailwind-source.css.

This approach is safe, keeps the original module intact, and ensures full Hyvä frontend compatibility.