— Technical

Migrating from Luma to Hyvä: what actually changes and how to approach it

23 April 2026 · 7 min read

magento hyva frontend performance migration

Hyvä is not a drop-in replacement for Luma. That distinction matters a lot when you’re planning a migration timeline, estimating scope, or explaining the work to a client who just wants a faster store.

This post is what I walk through with clients before we start a Hyvä migration — the architectural shift, what actually breaks, what survives intact, and how to sequence the work to avoid a big-bang relaunch.

Why Hyvä is architecturally different

Luma’s frontend is built on RequireJS, Knockout.js, and a UI Component framework that has accumulated significant complexity since Magento 2 launched. Every module that adds frontend functionality does so by registering components into this system — it’s how cart updates, configurable product options, minicart, and layered navigation all work.

Hyvä replaces the entire presentation layer. It keeps Magento’s PHP backend, service contracts, APIs, and database completely intact, but swaps the frontend stack for:

  • Alpine.js — a lightweight reactive library replacing Knockout
  • Tailwind CSS — utility-first CSS compiled at build time, replacing Less/CSS stacks
  • PHP View Models — data passed to templates via PHP classes rather than JavaScript initialisation

The result is dramatically less JavaScript reaching the browser. A typical Luma page ships 400–600KB of JavaScript before your custom code. Hyvä pages commonly come in under 50KB. That’s the source of the Lighthouse score improvements people talk about.

What survives the migration intact

Everything that lives in the Magento backend is untouched:

  • Database schema, all data
  • PHP service contracts and repositories
  • REST and GraphQL APIs
  • Admin panel, orders, customers, catalog management
  • Business logic in Models and ResourceModels
  • Message queues, cron jobs, observers, plugins

If your integration syncs orders to an ERP via REST, it continues working. If you have custom pricing logic in a plugin on \Magento\Catalog\Model\Product, it still fires. The backend is entirely unaffected.

What breaks

Everything that injects frontend behaviour via Luma’s JS stack breaks. Specifically:

RequireJS/Knockout components. Any module that uses requirejs-config.js to register a component or override a Knockout template has no equivalent in Hyvä. The module’s frontend code simply does nothing — it’s loaded but the hooks don’t exist.

UI Components. If a module renders anything via Magento’s uiComponent framework on the storefront (not admin — admin is fine), it won’t render under Hyvä.

.phtml templates that reference Luma JS. Templates that call require(['...']) or reference data-bind="..." attributes won’t function as expected.

Less/CSS custom styles. Hyvä doesn’t compile Less. Theme-level style overrides need to be rewritten in Tailwind utilities or custom CSS.

Auditing your extension stack

This is where most migration timelines get underestimated. You need to audit every third-party module that touches the storefront.

For each module, the question is: does it inject frontend code via RequireJS, Knockout, or Luma-specific templates?

# Find RequireJS config files in third-party modules
find vendor/ -name "requirejs-config.js" \
  -not -path "*/magento/*" \
  -not -path "*/hyva-themes/*"

# Find Knockout data-bind usage in templates
grep -rl "data-bind" vendor/ \
  --include="*.phtml" \
  --exclude-dir="magento" \
  --exclude-dir="hyva-themes"

For every module that comes back in that audit, you have three options:

  1. Vendor provides a Hyvä compatibility module — install it, done. Most major vendors (Amasty, Mirasvit, Mageplaza) do for their popular extensions.
  2. No compatibility module exists — evaluate whether a different extension covers the same need. For commodity functionality, this is often the right call.
  3. Business-critical, no alternative — budget for a custom Alpine.js implementation of the frontend portion. The backend stays, you’re only rewriting the presentation layer.

The checkout is a special case. Hyvä ships with the standard Magento checkout unchanged — you can migrate the store theme and leave checkout on Luma initially. Hyvä Checkout is a separate product that replaces the checkout with an Alpine.js implementation, and it has its own compatibility matrix. I typically recommend migrating the main theme first and addressing checkout separately.

What a phased migration looks like

The sequencing that works reliably:

Phase 1: Core theme and catalog pages. Install Hyvä, build your child theme, migrate header, footer, category pages, and product pages. This covers the bulk of the storefront and is where the performance gains show up. Leave checkout untouched.

Phase 2: Extension compatibility. Work through the audit list. Install vendor compatibility modules, build custom bridges for anything without one, and retire extensions that have better Hyvä-native alternatives.

Phase 3: CMS and content pages. Migrate content blocks, homepage, landing pages. These often have bespoke layouts that need careful work with Tailwind.

Phase 4: Checkout. Only after the main theme is stable and tested. Whether you go with Hyvä Checkout, One Step Checkout with Hyvä support, or leave the default checkout depends on your conversion requirements and extension dependencies.

The Tailwind compilation step

One thing that catches people: Hyvä’s CSS is generated at build time by Tailwind’s JIT compiler. It scans your templates for utility class usage and generates only the CSS those classes require.

This means two things in practice:

First, you need to run the Tailwind build as part of your deployment pipeline. It’s not optional — skipping it means CSS changes don’t make it to production.

Second, dynamically constructed class names (building a class string from a PHP variable) won’t be picked up by the scanner. Use complete class names in your templates.

// Wrong — scanner misses this
$class = 'bg-' . $color . '-500';

// Correct — scanner finds this
$class = match($color) {
    'red' => 'bg-red-500',
    'blue' => 'bg-blue-500',
    default => 'bg-gray-500',
};

Performance expectations

The Lighthouse score improvements are real but don’t treat them as automatic. Hyvä removes the JavaScript bottleneck, but if your server response time is slow, your images are unoptimised, or you have synchronous third-party scripts loading in <head>, those problems don’t go away.

In practice, on a well-prepared migration:

  • Mobile Lighthouse performance scores commonly move from 20–40 range on Luma to 70–90+ on Hyvä
  • Time to Interactive drops significantly because the JavaScript parse burden is removed
  • LCP and CLS improvements are largely down to your image optimisation and content strategy, not Hyvä itself

Common mistakes

Not testing offline mode. Extension compatibility issues often only surface under specific conditions — particular product types, specific discount combinations. Test against a production database snapshot, not just a handful of demo products.

Migrating checkout too early. Checkout is where money changes hands. Keep it stable on Luma while you validate the rest of the migration.

Assuming all Tailwind classes work in Astro/Magento attribute strings. (This one bites people in other frameworks too.) Always use complete class strings in templates.

Skipping the build step in CI. If your deployment pipeline doesn’t run npm run build-prod, the first deploy to production will be missing CSS changes.

On timeline

A realistic migration scope for a store with 10–15 third-party extensions, a custom theme, and moderate CMS content is typically 6–10 weeks of focused development. This assumes:

  • Clean Magento 2.4.x codebase, reasonably up to date
  • No deeply customised checkout
  • Vendor Hyvä compatibility modules available for the critical extensions

Stores with heavier customisation, older codebases, or large amounts of custom JavaScript can run significantly longer. The audit phase is the most reliable predictor of final scope.

If you’re evaluating whether Hyvä makes sense for your store, the extension audit is the right first step. The extension list tells you the real migration cost faster than any other analysis.

Savan Padaliya

Savan Padaliya

Senior Engineering Consultant

← Back to writing