How to Migrate from Luma (and Other) Themes to Hyvä?

A 0.1-second improvement in page load time increases ecommerce conversions by 8.4% - documented in a study from Deloitte. For Magento stores still running on the Luma theme, that fraction of a second is closer to two or three full seconds of unnecessary load. Luma ships roughly 0.9 MB of JavaScript and CSS per product page. Hyvä ships 0.15 MB. The gap in raw frontend weight is approximately 6x.

As of November 2025, 65% of live Hyvä-based Magento stores pass Google's Core Web Vitals, compared to 41% of stores running the standard Luma frontend (HTTP Archive data). That 24-point gap translates directly into search rankings, bounce rates, and revenue.

The migration calculus changed significantly in November 2025. On November 10, Hyvä founder Willem Wigman announced at Meet Magento Netherlands that the Hyvä Theme was going fully open source under OSL3 and AFL3 - the same licenses Magento Open Source uses. The €1,000 per-store license fee that had been the main objection for mid-market merchants is gone. The paid products (Hyvä Checkout at €1,000, Hyvä UI at €250 one-off, Hyvä Commerce at €3,000/year) remain commercial, but the core theme no longer costs a license fee.

This guide covers the full migration process: pre-audit, installation, design transfer, extension compatibility, CMS content, testing, and go-live. It also covers migrating from custom Blank-based themes and third-party themes like Porto, Argento, or Ultimo - not just stock Luma, because most production stores are not running stock Luma anyway.

Why 2026 Is the Right Year to Move?

Three things converged in late 2025 that make deferring a Hyvä migration harder to justify.

First, the open-source release removed the licensing barrier. Second, Hyvä version 1.4.4 (released March 2026) ships with Tailwind CSS v4 and the Oxide Rust engine - faster build times and a CSS-first configuration model. The developer experience is better than it has ever been. Third, over 6,400 live Magento stores now run Hyvä, including Nestlé, Volkswagen, Dunkin', Crocs, and Levi's. The extension ecosystem has matured to match.

The SEO pressure is real. Google's Core Web Vitals remain an active ranking signal, and the gap between a Luma store and a Hyvä store on mobile is typically measured in seconds, not milliseconds. Stores with 'Good' CWV scores see 24% higher mobile conversion rates than those scoring 'Poor' (Google 2024 ecommerce study). Mobile traffic now represents 60–70% of ecommerce visits.

Every month on Luma is compounding technical debt - more customizations that need porting later, more extensions drifting from Hyvä compatibility, more performance gap relative to competitors who have already migrated.

Why Luma Stops Working at Scale?

Luma shipped with Magento 2 in 2015. It was designed to showcase the platform's capabilities, not to win speed benchmarks. The technology choices it made - RequireJS, KnockoutJS, jQuery, and LESS - were reasonable for 2015. They are a liability in 2026.

The page weight problem is concrete. A default Luma storefront ships 2–4 MB of JavaScript and CSS on every page load. RequireJS loads module dependencies on demand, but 'on demand' in Luma terms means hundreds of separate files the browser must request, parse, and execute before anything interactive appears on screen. The KnockoutJS UI component system is heavyweight - the library alone weighs over 90 KB, and each UI component adds more.

The developer experience compounds the problem. Luma's XML layout system, PHTML templates, and RequireJS module graph are deeply intertwined. Changing a navigation component means touching layout XML, override templates, and JS module declarations across multiple files. That maintenance burden slows down every customization and makes every Magento upgrade riskier.

From a Core Web Vitals standpoint, Luma struggles with LCP (Largest Contentful Paint) and TBT (Total Blocking Time) because the browser cannot render meaningful content until heavy JavaScript finishes executing. On mobile, this results in Google PageSpeed scores routinely in the 20–50 range without significant additional optimization work.

What Actually Changes When You Migrate to Hyvä?

Migrating to Hyvä is not a theme switch - it is a frontend rebuild. Understanding what changes prevents scope surprises.

Luma's frontend stack relies on RequireJS for module loading, KnockoutJS for data binding, jQuery for DOM manipulation, and LESS for CSS preprocessing. Hyvä removes all four. In their place: Alpine.js handles interactivity and Tailwind CSS handles styling.

What transfers with minimal work: your Magento backend, database, product catalog, admin configuration, and most backend-only extensions.

What does not transfer automatically: custom layout XML overrides, .phtml templates that use Knockout or jQuery, LESS stylesheet customizations, widget configurations that reference Luma-specific blocks, and any extension that renders frontend HTML through the legacy JS stack.

Simple stores with stock Luma and few third-party extensions can migrate in a few weeks. Stores with years of custom frontend work, bespoke checkout modifications, and 20+ third-party modules are looking at a 3–6 month project.

Luma vs. Hyvä vs. Other Frontends: The Honest Comparison

PWA Studio gives you a full decoupled architecture but requires a GraphQL API layer between Magento and the frontend - a legitimate approach for teams with deep React expertise. For most merchants, especially those on Magento Open Source, Hyvä delivers PWA-level page speed without the headless complexity. Hyvä Checkout (€1,000) adds a React-based, conversion-optimised checkout on top of the Hyvä theme if that is your priority.

Alpine.js at roughly 15 KB gzipped replaces KnockoutJS (90+ KB) for reactive UI. Tailwind CSS, built at compile time and purged to only the classes your templates actually use, produces stylesheets of 5–20 KB rather than Luma's 250+ KB compiled bundles. Hyvä does not change Magento's XML layout system entirely - layout XML files and PHTML templates are still how you structure pages. What it eliminates is the KnockoutJS UI component layer and RequireJS module graph.

Is Migration Worth It for Your Store?

Good candidates for migration

• Stores with PageSpeed mobile scores below 60 - Hyvä typically pushes these into the 80–100 range
• Stores planning a redesign already - rebuilding templates on Hyvä while redesigning adds little incremental cost
• Stores where frontend development has become slow and expensive due to Luma's complexity
• Stores where mobile conversion rate is lagging despite healthy traffic - faster LCP has a measurable revenue impact
• Stores on Magento 2.4.4-p9 or higher with PHP 8.1+ (Hyvä's minimum requirements as of 2026)
• Stores already using Hyvä-compatible extensions - compatibility work is minimal
• Teams actively adding new features to the storefront - Hyvä's simpler architecture makes ongoing development faster

When to wait or think carefully

• Stores with a large number of highly customised legacy extensions with no Hyvä-compatible versions
• Stores planning a platform migration to Shopify or Commercetools within the next 12 months
• Stores mid-way through another major project (Magento upgrade, ERP integration) - do one thing at a time
• Heavily customised B2B workflows built in Knockout - these can be ported but require significant custom work
• Very small stores with tight budgets and few performance complaints - the ROI math may not work at sub-$8,000 project sizes
• Stores with checkout extensions that have no Hyvä compatibility module and no vendor roadmap

Environment Requirements

Before starting, confirm your Magento installation meets Hyvä's minimum requirements (per official Hyvä documentation):

• Magento 2.4.4-p9, 2.4.5-p8, 2.4.6-p7, 2.4.7-p1 or higher
• PHP 8.1 or higher
• Node.js 20.0.0 or higher (for Tailwind CSS compilation on dev/staging)
• A free Hyvä Packagist key from your hyva.io account (required for composer install)

Step 1: The Pre-Migration Audit - Do This Before Anything Else

The extension compatibility audit is the most important step in any Hyvä migration, and the one most teams skip or rush. Every budget overrun and project delay in Hyvä migrations traces back to an extension that needed more work than expected. The audit takes a day or two and prevents weeks of mid-project surprises.

Inventory your current theme stack

Run the following to get a full list of active modules:

Also check composer.json and app/code to catch any modules not surfaced by the CLI command. Create a spreadsheet with four columns: Module Name, Affects Frontend (Y/N), Hyvä Compatibility Module Exists (Y/N/Custom), and Action Required.

Classify your extensions

Backend-only modules - payment processors, ERP connectors, inventory systems - generally work without any changes. Extensions that need compatibility work fall into predictable categories:

• Storefront widgets: Product sliders, mega menus, layered navigation, banners - almost always built on jQuery and need Hyvä compatibility modules or Alpine.js rewrites.
• Checkout modifications: Custom checkout steps, one-page checkout replacements, or payment gateway integrations that hook into the checkout JS. These are the highest-risk items.
• Search and navigation: Elasticsearch-powered search overlays, autocomplete modules, and layered navigation filters typically require Hyvä-specific versions from the vendor.
• Review and social proof: Product review carousels, rating widgets, and UGC modules that render on the storefront.

For each frontend-affecting extension, check the official Hyvä compatibility list at hyva.io or the extension vendor's documentation. The three outcomes you will see:

• Extension has an official Hyvä compatibility module - install it alongside the main extension, done.
• Extension has no official module but is backend-only - no work needed on Hyvä.
• Extension has frontend components with no Hyvä module - needs custom compatibility work.

If you're running MageDelight extensions, this step gets simpler: MageDelight offers 45+ Hyvä-compatible extensions including their popular Mega Menu, Subscribe Now Pro, Mobile OTP Login, Advanced Review Ratings, and Shop By Brand - and when Hyvä went open source in November 2025, MageDelight added Hyvä compatibility to their modules at no additional cost. That's a meaningful reduction in compatibility work if your store already uses their extension stack.

Checkout is a special case

The Luma checkout is the heaviest page in any Magento store - it loads 400+ JavaScript files and relies entirely on KnockoutJS. Hyvä's frontend replaces the Luma storefront pages, but the default Luma checkout can remain in place as a fallback. If you want a fully Hyvä-native checkout, that requires Hyvä Checkout (€1,000). For many stores, deploying Hyvä on all storefront pages while keeping the Luma checkout is a practical first phase.

Run a performance baseline

Before touching anything, capture your current scores using Google PageSpeed Insights on your homepage, a representative category page, and a product page. Screenshot the results - you will need these numbers after migration to demonstrate the improvement, and to identify whether remaining issues are frontend (Hyvä territory) or backend (server, database, third-party JS).

Step 2: Set Up a Staging Environment

Never start migration work on a live store. Clone your production database and codebase to a staging server, verify the clone is working correctly, then lock the staging environment so it does not receive production orders or trigger payment webhooks.

Do all migration work on this branch. This gives you a clean rollback path if something goes wrong mid-migration.

Step 3: Install Hyvä via Composer

Since November 2025, Hyvä Theme is available for free. Create a free account at hyva.io to get your Packagist Composer keys. Then:

After installation, activate the theme in Magento Admin under Content > Design > Configuration. Apply it to your store view. At this point, your storefront will render in Hyvä's default state - stripped of your Luma customizations, but loading fast. This is your starting point, not your ending point.

Step 4: Migrate Your Design - Child Theme Setup

Create a child theme that inherits from Hyvä rather than from Luma. The directory structure is:

Inside that directory, you need theme.xml (declaring the parent as Hyvä), registration.php, and your design files. Your brand colors, typography, and layout go into Tailwind CSS configuration rather than LESS variables. Create a tailwind.config.js in the theme root and reference your design tokens:

Your existing LESS overrides, custom .phtml templates, and layout XML files need to be reviewed one by one. Start with your product page, category page, and header - these affect every session. Templates are rewritten using Alpine.js directives instead of Knockout data bindings. The underlying PHTML structure carries over; only the JS/template layer changes.

The Tailwind build step runs on development or staging and generates the purged CSS file. This build must run as part of your deployment pipeline - if it does not, your production store will have no CSS.

Step 5: Handle Extension Compatibility

This is the most variable step in any Hyvä migration. The process for each affected extension:

1. Check whether the extension vendor provides a Hyvä compatibility module. Most major extension providers do now - check their release notes or the Hyvä compatibility tracker.

2. If a vendor module exists, install it alongside the main extension.

3. If no vendor module exists, you need a custom compatibility module - rewriting the extension's frontend templates from Knockout/jQuery to Alpine.js and Tailwind CSS. The backend PHP logic usually survives untouched.

4. After installing or building each compatibility module, run setup:upgrade and flush cache, then test that specific feature end-to-end before moving to the next extension.

80–90% of a typical Luma extension's code can be reused as-is. It is the frontend templates and KnockoutJS components that need to be rewritten in Alpine.js.

For stores using MageDelight's extension suite, Hyvä-compatible versions of all 45+ modules are available at no extra cost - covering everything from their Mega Menu and Subscription extensions to their Advanced Promotions and OTP Login module. This is worth verifying before you build custom compatibility layers you don't need.

Step 6: Migrate CMS Content and Layouts

CMS pages, blocks, and widgets built in Luma often reference Luma-specific layout handles, block classes, or widget instances that do not exist in Hyvä. Audit every CMS page and block in your store and update references to Hyvä equivalents.

Widget instances are the most common problem. If you have used Luma's product slider widgets or promotional banner widgets on your homepage, those will either need Hyvä-compatible replacements or custom rebuilds. Static blocks that contain only HTML and CSS (no widget instances) typically migrate without issues.

Hyvä supports standard Magento layout XML, so page structure carries over. Only the JS/template layer needs rebuilding.

Step 7: Testing and QA

Test across devices and browsers systematically before go-live. The minimum test matrix:

• The full customer journey: browse category → apply filter → open product → add to cart → checkout to order confirmation
• Account functions: registration, login, order history, address book
• Search: basic keyword search, autocomplete, no-results state
• Mobile: portrait and landscape on both Android and iOS
• Performance: run Google PageSpeed Insights on staging; compare against your baseline

Pay particular attention to the checkout. Checkout customizations that were working on Luma are the most likely source of silent failures - they may appear to render but fail at specific steps. Test with multiple payment methods if your store supports them.

Step 8: Go Live

Schedule go-live during a low-traffic window. Take a full database and file backup immediately before switching. The switch is just pointing the production store to the Hyvä theme in Admin > Content > Design > Configuration - the actual deployment is fast, but document your rollback steps before you begin.

After go-live, monitor real-user performance data in Google Search Console and Google Analytics for 72 hours. Lighthouse scores on staging are lab data; real-user Core Web Vitals from CrUX data give you the actual picture. Keep the Luma theme files installed but inactive - useful as a fallback if critical issues surface.

Monitor checkout conversion rates in the first week after go-live to catch any functional regressions quickly. Core Web Vitals improvements appear in Google Search Console quickly, but full SEO ranking impact accumulates over 3–6 months.

Migrating from Custom Themes (Not Just Luma)

Most production stores are not on stock Luma - they are on a heavily customised child theme, a third-party marketplace theme, or a fully custom build. Here is what changes for each.

Custom Luma child themes

Your child theme's LESS overrides, custom layout XML, and template overrides all need to be ported to Hyvä's Tailwind + Alpine stack. There is no shortcut. Your brand identity - colors, typography, component patterns - translates directly into Tailwind configuration. The work is rewriting how those styles are applied, not redesigning from scratch.

Third-party themes (Porto, Argento, Ultimo, etc.)

These themes bundle their own component libraries, JavaScript widgets, and sometimes bundled extensions. Before migrating, check whether the theme vendor offers a Hyvä-compatible version - Porto and a handful of others do. If not, treat the theme the same as a heavy custom Luma child: inventory every custom component, identify which ones have Hyvä equivalents, and plan rebuilds for the rest.

The complication with bundled themes is that their UI components and included extensions are often tightly coupled. Separating them - keeping the backend extension but replacing the frontend component - requires understanding the original theme's architecture. Also inventory the theme's own JavaScript files separately from installed extensions; they all need to be rebuilt or replaced.

Magento Blank-based custom themes

Stores built from Blank rather than Luma have less Knockout and jQuery in the frontend by default, but also have fewer community compatibility modules available (since most are written against Luma). The advantage is that you are not fighting Luma's opinionated component library. The migration approach is the same: audit extensions, port templates to Alpine/Tailwind, build or source compatibility modules.

Incremental Migration: A Lower-Risk Approach for Complex Stores

For stores with many extensions, heavy customizations, or limited development bandwidth, a full cutover from Luma to Hyvä in a single project is high-risk. Hyvä supports multi-theme configurations where different store views run different themes, which enables an incremental approach.

A common incremental sequence:

• Migrate the homepage and category pages first - these get the most traffic and benefit most from faster LCP.
• Migrate product detail pages next - these drive conversions directly.
• Migrate cart and secondary pages.
• Address checkout last - either keeping Luma checkout or migrating to Hyvä Checkout as a separate project.

The Läderach (Swiss chocolatier) migration is a real-world example: after a 6-month migration to Hyvä with Adobe Commerce, their homepage and PDP scored 93 on PageSpeed for desktop. That result came from a structured migration, not a rushed full cutover.

The Hyvä Extension Ecosystem

The ecosystem now includes over 1,200 compatible extensions, and many of the largest extension vendors have made Hyvä compatibility a standard part of their release process. The practical question is not whether Hyvä has extensions - it does - but whether the specific extensions your store depends on are covered.

When an extension you need does not have a Hyvä-compatible version, rewriting it is a defined process: 80–90% of the backend code survives intact. Only the frontend templates and KnockoutJS components need to be rewritten in Alpine.js. The Hyvä documentation on extension compatibility covers this process in detail.

What Goes Wrong - and How to Avoid It

Skipping the extension audit

This is the single most common cause of budget overruns. Teams that start by installing Hyvä and switching their production store view immediately surface compatibility issues under pressure, rather than discovering them in a controlled audit. Always audit before installing.

Treating checkout as an afterthought

The Luma checkout is the heaviest page in any Magento store. If you migrate the storefront to Hyvä but keep the Luma checkout without a plan, you have a fast storefront leading to a slow conversion point. Address checkout strategy explicitly at the start of the project, even if execution is deferred.

Not building on staging first

Every phase of the migration - theme installation, extension compatibility, template rebuild - should be completed and tested on staging before touching production. Broken frontend on a live store is a revenue problem.

Forgetting the Node.js build step

Hyvä uses Tailwind CSS, which requires a Node.js build process to generate the purged CSS file. This build should run on development or staging, not on production. If your deployment pipeline does not include this step, your production store will have no CSS. Node.js 20.0.0 or higher is required.

Ignoring post-launch monitoring

Core Web Vitals improvements are real but not always instant in terms of SEO impact - Google's crawl cycle means full ranking effects take 3–6 months. Set up monitoring in Google Search Console before launch so you have a clean before/after data record.

Realistic Migration Timelines and Costs

These figures assume you're hiring a Hyvä-specialist agency or team. In-house teams with Magento frontend experience can reduce external costs but need to budget for Alpine.js and Tailwind CSS learning time if the team hasn't used them before.

If budget is a constraint, MageDelight's Hyvä Quick Launch Solution is worth considering for smaller stores - it's a rapid deployment package designed to get a Hyvä storefront live within 25 days. It's not a full bespoke migration, but for merchants who need to move fast without the enterprise price tag, it's a pragmatic option.

For ongoing costs: the Hyvä Theme core is free. If you want the Hyvä UI component library, that's €250 per store. Hyvä Checkout is €1,000. Hyvä Enterprise (for Adobe Commerce-specific features) is €2,500. Hyvä Commerce - the full suite with CMS, admin panel, and media optimisation - is €3,000 per year.

Real Performance Results: What to Actually Expect

Three data points worth knowing, all from documented case studies rather than modeled estimates:

• Byggmax (large Nordic retailer): Scandiweb's migration moved the PLP PageSpeed score from 85 to 99 on desktop and the PDP from 70 to 87.
• Classic Football Shirts: Scandiweb reported a 2.5x PageSpeed improvement with improvements across all Core Web Vitals, including notably faster stock updates and cart interactions.
• ImaginFires (UK bioethanol retailer): 296% improvement in site speed, Lighthouse score pushed above 80 during their peak winter season after migrating to Hyvä.

One important caveat: Hyvä fixes frontend-sourced performance problems. If your store's slowness is primarily backend - slow database queries, misconfigured Varnish, undersized server, or too many third-party JS libraries from analytics and marketing tools - Hyvä will help but won't eliminate the issue. A performance audit before migration clarifies what portion of your score gap is frontend-fixable.

When to Bring in Professional Help?

The migration process is technically doable in-house if your team knows Magento development. The honest trade-off: an in-house migration takes longer, produces more surprises, and requires your team to learn Alpine.js and Tailwind CSS on the job. An experienced Hyvä development partner compresses the timeline and brings pattern-matching knowledge from prior migrations.

If you are looking for a partner that combines Hyvä development capability with a large library of already-compatible extensions, MageDelight's Hyvä Theme Development Services cover the full scope: store audit, migration planning, custom theme development, extension compatibility, and ongoing support. As an official Hyvä Partner, their team has direct access to Hyvä's technical documentation and update cycles.

For stores where speed is the priority, MageDelight's Hyvä Quick Launch Solution targets a 25-day delivery for stores with a relatively clean extension stack. This is a fixed-scope package, not a blank-check engagement - useful for stores that need to move fast and whose requirements fit the package.

For stores that just need a technical assessment before committing, MageDelight also offers a Magento Audit Service that covers extension compatibility, performance baseline, and migration complexity estimation. That gives you the numbers to make the build-vs-buy decision.

The Bottom Line

Hyvä is the right frontend choice for the vast majority of Magento 2 stores in 2026. The license cost is gone. The ecosystem is mature. The performance gap between Hyvä and Luma is real and documented. The question is no longer whether to migrate - it is when and with how much scope.

The extension audit is the first step and the most important one. Run it before making any other decisions. It will tell you the real scope, the real timeline, and the real cost. Everything else in the migration follows from that.

For stores on Magento 2 that plan to stay on the platform, Hyvä is not experimental anymore - 65% of Hyvä-based stores now pass Core Web Vitals, brands like Volkswagen and Dunkin' have deployed it, and the ecosystem supports over 1,200 extensions. The stores that will feel this decision most sharply are the ones that stay on Luma for another 12 months while their Hyvä-powered competitors widen their Core Web Vitals advantage. The frontend work will eventually happen regardless - doing it now, while migration patterns are well-established and the extension ecosystem is mature, is cheaper and less disruptive than doing it under pressure in two years.

Also read: Hyvä Theme Benefits For Your Magento 2 Store