The Luma to Hyva migration checklist

Part 10 of the Hyva series — the bridge from building to shipping. Includes tooling links.

The order of work matters

A Hyva migration is not "turn it on and fix what breaks." The stores that cut over cleanly follow a fixed sequence, because each phase unblocks the next. The order below comes from several production cutovers (project names withheld); reversing it is the usual cause of a stalled migration.

Phase 0 — Inventory

List every module that renders frontend. For each, mark: plain PHTML (works as-is), Knockout/Luma-template (needs a Hyva template), or JS-only injection (needs a compat module). The count of the last two is your compatibility backlog and your timeline.

Stand up a throwaway copy of the store to measure and test against. Govard gives you a working Magento with the storefront running in one govard env up, so you can benchmark Luma as-is, then prototype the Hyva child theme against the same catalog without touching production.

Phase 1 — Theme and pipeline

Scaffold the child theme, configure Tailwind, and get a minimal page rendering. Do not port features yet — get the build green and the page weight small first. This proves the pipeline before you invest in templates.

Phase 2 — Catalog and content

Migrate category, product, CMS, and search pages. These are the highest-traffic surfaces and the biggest performance win, so doing them first shows value early. Most of this is PHTML overrides plus the layered-navigation compat module if you use faceted search.

Phase 3 — Compatibility modules

Work the inventory backlog from Phase 0: AJAX cart, CAPTCHA, gift cards, FAQ, social login, brand widgets, and any inventory/store-locator UI. Each is a small template plus an Alpine component around the existing endpoint (see the compatibility post for the pattern).

Phase 4 — Checkout

Hyva Checkout is a separate module (covered in the advanced part of this series). Plan it as its own phase: upgrade the checkout module, port any custom checkout steps, and verify payment methods end-to-end. Checkout is where cutovers most often discover a hidden dependency, so isolate it from the catalog work.

Phase 5 — CSP and cleanup

Hyva changes the script and style sources, so Content Security Policy needs revisiting. Many migrations consolidate a bespoke CSP plugin into Hyva's built-in CSP handling and fix the few directives the main menu and cart actually need. Do this last, after every template is stable, so you are whitelisting a known set rather than chasing a moving target.

Go-live checklist

• All interactive modules render on Hyva (inventory from Phase 0 closed).
• Category, product, CMS, and search verified on a staging copy.
• Checkout exercised end-to-end, including guest and one logged-in path.
• Payment methods confirmed (including any wallet/express option).
• CSP reviewed; no console violations on key pages.
• Lighthouse / WebPageTest on category and product pages meets target.
• Full-page cache confirmed serving Hyva pages (no JS dependency left un-cached).
• Rollback plan: keep the Luma theme assigned and switchable per store view.

De-risking the cutover

Two practices separate clean cutovers from painful ones:

1. Per-store-view switch. Assign Hyva to one store view first (or a staging host), keep Luma on the rest, and flip traffic only after verification. Magento lets you switch the theme per store view, so rollback is a config change, not a deploy.
2. Measure before and after. Capture Lighthouse and server-timing on the Luma pages, then the same pages on Hyva. The delta is your justification and your regression alarm. Govard's audit workflow and the maestro-skills review/audit skills help you capture those numbers and keep the diff reviewed as you go.

What's next

The core migration is done. The advanced part of the series goes deeper on the pieces teams most often defer: Hyva Checkout, Hyva React with GraphQL, and performance hardening.

Next in this series: Hyva Checkout — the React-based checkout — /blog/magento2-hyva-checkout