Migrating from Luma to Hyvä: A Practical Guide for Magento 2 Stores
A step-by-step playbook for moving a Magento 2 store from Luma to Hyvä — auditing extensions, setting up a child theme, porting templates to Alpine.js, and shipping without surprises.
Luma has carried Magento 2 storefronts for years, but its RequireJS + KnockoutJS stack ships a lot of JavaScript. Hyvä replaces that frontend with Alpine.js and Tailwind CSS, and the result is usually a dramatic jump in Core Web Vitals.
Not sure Hyvä is right for your store yet? Start with Hyvä vs Luma. This guide is the process I follow on real migrations — what to audit, what to build, and where projects usually slip.
Why Hyvä is worth it
- Far less JavaScript — Alpine.js components replace most of the RequireJS/Knockout tree.
- Utility-first CSS — Tailwind purges unused styles at build time, so you ship only what each page uses.
- Better developer experience — templates are plain PHTML + Alpine, no UI-component XML gymnastics for every frontend change.
- Same Magento backend — catalog, checkout logic, and admin stay untouched.
Measure before you start
Record Lighthouse and CrUX field data for your top templates (home, category, product, cart) before the migration. You'll want a baseline to prove the win.
Step 1 — Audit your extensions
Every third-party module that touches the frontend needs a Hyvä-compatible version. Build a spreadsheet with three columns:
| Module | Frontend impact | Hyvä status |
|---|---|---|
| Payment gateway | Checkout JS | Compat module available |
| Product labels | PHTML + JS | Needs porting |
| Admin-only ERP sync | None | No action |
Check the official Hyvä compatibility tracker first. Anything without a compat module becomes a porting task in your estimate.
Step 2 — Install Hyvä and create a child theme
After installing the Hyvä packages with Composer (you'll need your license credentials), create a child theme so your customizations survive upgrades:
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
<title>Acme Hyvä</title>
<parent>Hyva/default</parent>
</theme><?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(ComponentRegistrar::THEME, 'frontend/Acme/hyva', __DIR__);Copy the parent theme's web/tailwind folder into your child theme, then point the Tailwind config at both your templates and the parent's.
Step 3 — Port templates to Alpine.js
Most Luma customizations are Knockout bindings or jQuery widgets. In Hyvä, the same behaviour is usually a few lines of Alpine. Here's a "quantity stepper" component:
<div x-data="{ qty: 1 }" class="flex items-center gap-2">
<button type="button" class="btn" @click="qty = Math.max(1, qty - 1)" aria-label="Decrease">−</button>
<input name="qty" type="number" min="1" x-model.number="qty" class="w-16 text-center form-input" />
<button type="button" class="btn" @click="qty++" aria-label="Increase">+</button>
</div>For reusable logic, register the component as a function in a <script> block and reference it from x-data, keeping templates readable.
Step 4 — Decide on checkout
Checkout is the riskiest page. You have two common options:
- Keep the Luma checkout via Hyvä's fallback mechanism — fastest to ship.
- Hyvä Checkout — a fully rebuilt, faster checkout, but payment and shipping modules need compatibility.
Don't migrate checkout blindly
Test every payment method, shipping carrier, and coupon flow on staging. Revenue lives on this page.
Step 5 — QA, performance, and launch
- Run visual regression on your top 20 URLs.
- Re-run Lighthouse on the same templates as your baseline.
- Check structured data and meta tags are still rendered.
- Deploy behind a feature branch on staging; get client sign-off before production.
Typical results
On a well-executed migration it's common to see Lighthouse performance scores move from the 30–50 range into the 90s on mobile, with noticeably faster LCP and far smaller JS payloads. Exact numbers depend on your extensions and content — which is why the audit in Step 1 matters so much.
Planning a Hyvä migration? See my Hyvä theme development service and get in touch — I'll help you scope it.
