Hyva compatibility modules for third-party extensions

Part 9 of the Hyva series — building the core storefront. Implementation-focused, drawn from real migration experience (project names withheld).

Why compatibility is the real work

The theme and the Tailwind pipeline are solved problems — you set them up once. The work that actually varies project to project is the compatibility layer: the set of third-party extensions that ship Luma PHTML and Knockout widgets but no Hyva template. On a typical merchant storefront, this is where the schedule lives.

Hyva renders any module whose frontend is plain server-side PHTML without modification. The modules that need work are the ones that inject interactive JavaScript or rely on Luma-specific markup. Inventory them early (the migration checklist post shows how) and the rest of the project is predictable.

Extension categories, ranked by effort

From migrations of mid-size catalog stores, these are the categories that most often need a Hyva template, roughly in order of frequency:

1. Layered navigation / faceted search — especially when backed by Elasticsearch or OpenSearch. The filter widgets are heavily Knockout-driven; a Hyva port rebuilds them as Alpine components hitting the same search endpoint.
2. AJAX cart and quick-view — add-to-cart, mini-cart, and product quick-view popups. The Luma versions are Knockout; the Hyva versions are small Alpine components around the existing cart controller.
3. CAPTCHA / bot protection — form protections that inject their own JS. These need a Hyva-compatible template that loads the same challenge but without the Luma requirejs graph.
4. Gift cards and store credit — balance display, apply forms, and checkout integration. Mostly PHTML plus a little Alpine for the apply flow.
5. FAQ and content widgets — accordions, tabs, brand sliders. Low logic, pure markup, fast to port.
6. Social login — the buttons and the post-auth redirect. Usually a template swap plus ensuring the provider's script loads under Hyva's single JS file.
7. Brand / manufacturer widgets — brand sliders and filters on the category page. Markup-heavy, logic-light.
8. Inventory / store locator — store pickup and geolocation UIs. These are the heaviest, because they mix maps, distance calculation, and session state; budget them separately.

This list is not exhaustive, but it captures where weeks — not days — accumulate.

Structure of a compatibility module

A Hyva compatibility module follows the normal Magento module layout; it only adds a view/frontend/templates override and, where needed, an Alpine component. It does not patch the original extension — it provides the Hyva-shaped presentation alongside it.

ExampleStore/CompatGiftCard/
  registration.php
  etc/
    module.xml
  view/frontend/
    templates/
      giftcard/apply.phtml
    web/
      js/apply.js   (Alpine.data component)

The template renders Tailwind markup and binds the Alpine component:

<form x-data="giftCardApply" @submit.prevent="submit">
  <input name="code" x-model="code" class="rounded border border-border px-3 py-2">
  <button x-bind:disabled="loading">Apply</button>
  <p x-show="error" x-text="error" class="text-red-600 text-sm"></p>
</form>

The original extension's PHP (the apply controller, the balance model) is untouched — you are replacing the face, not the engine.

A pattern that recurs: keep the endpoint, swap the face

Almost every compatibility task reduces to the same shape:

1. Find the original Luma template and its Knockout bindings.
2. Identify the server endpoint or controller it calls.
3. Write a Tailwind PHTML that calls the same endpoint from Alpine.
4. Confirm the response shape matches what the Luma widget expected.

When an extension exposes a clean controller or GraphQL resolver, step 3 is trivial. When it hides logic inside a Knockout uiElement, you may need to read the original JS to learn the endpoint — that reconnaissance is most of the effort.

What to outsource vs build

Before writing a compat module, check whether the vendor already ships a Hyva compatibility package or the community has one. Many popular extensions do. For the long tail of niche or abandoned extensions, you write the template yourself — and that is fine, because each one is small once the endpoint is known.

The migration checklist post turns this inventory into a go/no-go per module and a realistic timeline.

What's next

With the theme built and the compatibility layer understood, the next post assembles them into a migration plan: the order of work, the go-live checklist, and how to de-risk the cutover.

Next in this series: The Luma to Hyva migration checklist — /blog/magento2-hyva-migration-checklist