Magento 2 Luma to Hyvä Migration Guide
If you’re running a Magento 2 store on the default Luma frontend, you’ve probably noticed your PageSpeed scores aren’t great. Maybe you’ve Googled “why is my Magento store so slow” more than once. The answer, in almost every case, is Luma’s frontend architecture — it’s shipping hundreds of kilobytes of JavaScript that your customers’ browsers have to chew through before anything useful happens on screen.
Hyvä fixes that. It’s a ground-up frontend replacement built by Willem Wigman that swaps out Luma’s RequireJS/Knockout/jQuery stack for Alpine.js and Tailwind CSS. The JavaScript payload drops by roughly 90%. Pages load in 1–2 seconds instead of 6–10. And your Core Web Vitals go from red to green.
But — and this is the part most “Hyvä is amazing” articles skip — the migration itself isn’t trivial. It’s a real project with real complexity, and things can go sideways if you don’t approach it right. We’ve done this 50+ times at Rock Technolabs. Some of those were clean, smooth projects. Some were rescues of botched migrations from other agencies. Here’s what we’ve learned.
Why This Matters More in 2026 Than It Did in 2023
Three years ago, migrating to Hyvä was a nice-to-have. The ecosystem was young, extension compatibility was spotty, and you could still get away with mediocre Core Web Vitals if your content was strong enough.
That window has closed.
Google’s been ratcheting up the weight of page experience signals steadily since 2021. The March 2025 core update hit slow e-commerce sites particularly hard — we saw Luma-based stores lose 15–30% of their organic visibility practically overnight. Meanwhile, competitors who’d already migrated to Hyvä or headless architectures held steady or gained.
The math is simple. If your Luma store scores 32 on mobile PageSpeed and your competitor’s Hyvä store scores 91, Google sees a quality gap. When everything else — content, backlinks, authority — is roughly equal, that gap becomes the tiebreaker. And in competitive e-commerce niches, tiebreakers decide who gets the sale.
There’s also the conversion angle. Google and Deloitte published research showing each 100ms of load time improvement lifts conversions by about 1–2%. Hyvä’s typical improvement is 3–5 seconds. On a store doing $500K/year, our clients regularly see $40K–$80K in recovered annual revenue just from the speed improvement. The migration pays for itself fast.
And then there’s the developer cost thing that nobody talks about. Luma’s LESS files are nested six levels deep. A CSS change that should take 20 minutes takes 3 hours because you’re fighting the cascade. With Tailwind, you add a utility class and move on. Our clients’ ongoing maintenance costs drop noticeably after migration — fewer dev hours for every frontend ticket. That compounds month over month.
And with Hyvä now being open source and free, the barrier to entry has dropped to basically zero. There’s no credible reason left to stay on Luma in 2026.
Before You Touch Any Code
I’m going to be blunt here: every single Hyvä migration we’ve seen go off the rails — including the ones we were hired to fix — skipped pre-migration planning. They jumped straight into development, discovered compatibility issues halfway through, and ended up 2–3× over budget with a frustrated client.
Don’t be that project. Here’s what needs to happen first:
Complete every item before writing a single line of Hyvä code. Seriously.
The extension audit — items 1 and 2 — is the one that really matters. It determines your entire project scope. A store with 12 extensions that all have Hyvä-compatible versions is a fundamentally different project from a store with 25 extensions where 8 of them need custom compatibility work. You can’t estimate timeline or cost without this data.
The 6-Phase Migration Process
Every migration we run follows this general structure, though the details flex depending on the store. I’ll walk through each phase with the actual commands and decisions involved.
Phase 1 — Extension Compatibility Audit
SSH into your Magento instance and pull your module list:
# Get all enabled third-party modules
bin/magento module:status --enabled | grep -v Magento_
# Or via Composer for a cleaner list
composer show -i | grep -v magento/Take that list, open the Hyvä Compatibility Module Tracker, and categorise every extension. You’ll end up with four buckets: modules that have official Hyvä versions (easy swap), modules that need a custom compatibility layer (8–40 dev hours each, depending on frontend complexity), modules that are so deeply tied to Knockout that they need a full replacement, and backend-only modules that don’t need any changes at all.
Put this in a spreadsheet — module name, vendor, compatibility status, action needed, estimated hours. This document drives everything downstream.
This phase takes 2–5 days. Don’t rush it. The time you spend here saves you multiples later.
Phase 2 — Environment Setup
Your live Luma store keeps running. Everything happens on staging.
# Add Hyvä repository (you'll need your license key from hyva.io)
composer config repositories.hyva-themes \
composer https://hyva-themes.repo.packagist.com/
# Install Hyvä
composer require hyva-themes/magento2-default-theme
bin/magento module:enable Hyva_Theme Hyva_ResetTheme
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -fThen configure your brand tokens in tailwind.config.js — primary colour, secondary, accent, and font family. Set the theme to “Hyva/default” in Content → Design → Configuration, flush caches, and verify. Your staging store will look bare-bones. That’s fine — it means the framework is installed correctly.
This usually takes a day or two. Nothing complicated, but do verify everything works before moving on. If you want more detail on the installation steps, we covered Hyvä’s features and installation process in a separate post.
Phase 3 — Template Migration (This Is Where the Real Work Is)
Here’s where most development hours go. Every custom Luma .phtml template gets rebuilt using Alpine.js and Tailwind. We work through them in customer-journey order:
Header and navigation first — it’s on every page, so you want it right early. Mega menus need special attention because Luma’s Knockout-based nav is completely replaced. Then homepage and CMS pages (usually straightforward unless you’ve got heavy Page Builder customisation). Category pages and layered navigation next — if you’re using Amasty or Manadev for navigation, this is where your Phase 1 audit pays off. Product detail pages are typically the most customised part of any Magento store, so budget accordingly. Cart, mini-cart, and finally customer account pages.
Here’s what the code change actually looks like, using a price template as an example:
<!-- Luma way: Knockout.js binding -->
<span data-bind="text: getFormattedPrice(finalPrice)"></span>
<!-- Hyvä way: Alpine.js -->
<span class="text-xl font-bold text-gray-900"
x-text="hyva.formatPrice(finalPrice)"></span>One thing we learned the hard way early on: don’t try to “convert” Luma templates line by line. It’s tempting — you’ve got the existing file right there, seems like you should just swap the Knockout bits for Alpine equivalents. But the result is always bloated, fragile code that misses the whole point of Hyvä’s architecture. Start from Hyvä’s default templates and customise from there. It’s actually faster and produces better code.
This phase is the most variable — anywhere from 2 weeks for a simple store to 8+ weeks for something with heavy customisation. If you want to understand the full scope of what changes under the hood, our detailed Hyvä vs Luma comparison breaks it all down.
Phase 4 — Checkout
You’ve got a choice here. Hyvä offers a separate Checkout product (€500 license) that replaces Magento’s Knockout-based checkout with an Alpine.js flow. It loads dramatically faster — we’re talking 1–2 seconds vs 5–10 for the default.
Or you can keep Magento’s default checkout. It still works with Hyvä. The rest of your store gets the speed boost, but checkout stays slow. A lot of our clients start here and add Hyvä Checkout later, which is totally fine.
Our honest recommendation though? If checkout conversion matters to your business (and when doesn’t it?), the €500 for Hyvä Checkout is probably the highest-ROI line item in your entire migration budget. We’ve seen 15–22% improvements in checkout completion after switching. On most stores, that pays back the license cost within a week or two of sales.
Not sure about the difference between the base Hyvä theme and the full Hyvä Commerce offering? We wrote a Hyvä Theme vs Hyvä Commerce comparison that clarifies what you’re actually buying.
Phase 5 — Testing
Budget 15–20% of your project time for this. I know that sounds like a lot. It isn’t.
Walk through every customer journey manually — browse, search, filter, add to cart, apply a coupon, checkout as a guest, checkout as a logged-in customer, pay with every payment method you support, check order confirmation, view account dashboard. Do this on Chrome, Firefox, Safari (especially iOS Safari — it handles JS differently and is where weird edge cases love to hide), and Edge.
Test every extension that was migrated. A layered navigation module that works perfectly on category pages might break on search results. A payment gateway that processes new cards fine might fail on saved card re-charges. These things only show up when you specifically test for them.
Then run your benchmarks:
# Lighthouse from CLI — run on all key pages
npx lighthouse https://staging.yourstore.com \
--output=json --output-path=./lighthouse-home.json
# Compare against your Luma baseline from the pre-migration checklist
# If the scores aren't dramatically better, something's wrongAnd get your actual team — not developers — to use the staging store like real customers. They’ll find things that scripted testing never catches.
Phase 6 — SEO Validation and Go-Live
This phase is about protecting what you already have. The migration changes how pages render, not what they contain or where they live. But sloppy execution can still damage your rankings if you’re not careful.
Before flipping the switch, verify on staging:
- URLs are identical — no trailing slashes added or removed, no case changes
- Title tags and meta descriptions match production
- Canonical tags are present and correct
- Structured data (Product, Organization, BreadcrumbList) renders properly
- Robots.txt and sitemap are unchanged
- Internal links all resolve — template changes can silently break links
- Image alt text carried over on all product and category images
- H1s and heading structure match the live site
Then deploy:
bin/magento maintenance:enable
bin/magento setup:upgrade && bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush && bin/magento indexer:reindex
bin/magento maintenance:disableMonitor closely for the first 72 hours — error logs, Search Console 404 spikes, conversion rates. Every Hyvä project we do includes 1 month of free post-launch support because the first few weeks always surface edge cases that testing missed. That’s not a failure of testing — it’s just the reality of putting code in front of thousands of real users with real browsers and real edge-case behaviour.
Want us to handle the migration?
Free audit, fixed pricing, 1 month post-launch support. No surprises.
The Mistakes We Keep Seeing
We’ve both executed successful migrations and been called in to rescue failed ones. Here’s what goes wrong, in order of how often we see it:
Starting development before finishing the extension audit. This is the big one. A mid-sized fashion store in the UK came to us after their previous agency was 8 weeks into development and had just realised that 6 of their 22 extensions were deeply incompatible with Hyvä. The project was already 2× over budget with no end in sight. We had to essentially restart from Phase 1. If they’d done the audit first, it would’ve been a 10-week project. Instead it took 5 months.
Converting Luma templates line-by-line instead of starting from Hyvä defaults. It feels efficient. It isn’t. You end up with code that technically works but carries over Luma’s architectural baggage. Start fresh from Hyvä’s templates and add your customisations on top.
No performance baseline. If you don’t record your Luma scores before migration, you can’t prove the improvement after. Run PageSpeed Insights and save the reports.
Treating SEO validation as optional. We had a client (not ours originally) who launched their Hyvä store without checking structured data. Their Product schema was broken across every PDP. It took 3 weeks for Google to reflect the damage. Don’t let that happen to you.
Hiring a general Magento developer instead of someone with Hyvä experience. Hyvä has its own patterns, its own component architecture, its own way of handling events and state. A developer who’s great with Luma but has never touched Hyvä is going to learn on your dime. That learning curve adds weeks and costs money. Talk to a team that’s done it before.
Skipping Hyvä Checkout because “we’ll add it later.” Look, sometimes budget is tight and you have to prioritise. But if you’re going to add it eventually anyway, doing it during migration is way cheaper than as a separate project later. The checkout templates need testing alongside everything else — bolting it on afterward means re-testing the entire checkout flow from scratch.
Actual Results from Our Projects
I could give you marketing language here, but the numbers speak for themselves. These are production stores, measured via Google PageSpeed Insights mobile after migration, with at least 3 months of post-launch data for the traffic and conversion figures.
| Store | Extensions | Before | After | Organic Traffic Δ | Conversion Δ |
|---|---|---|---|---|---|
| Fashion B2C, US market | 18 | 32 | 91 | +42% at 6 months | +18% |
| B2B industrial supplier, UK | 12 | 28 | 88 | +31% at 4 months | +12% |
| Multi-store food brand, EU | 24 | 41 | 94 | +38% at 6 months | +22% |
| Electronics retailer, AU | 16 | 35 | 89 | +27% at 5 months | +15% |
A few notes on the organic traffic numbers. The gains aren’t purely from Core Web Vitals — that’s part of it, but faster pages also mean Google can crawl more of your catalogue in the same crawl budget, bounce rates drop because pages actually load before people leave, and engagement metrics improve across the board. It’s a compounding effect. The stores that see the biggest jumps tend to be the ones that had the worst Luma scores to begin with — more room to improve.
We haven’t listed a project that went poorly because we’re being selective? No. We’ve had projects with lower gains — a B2B store with a tiny catalogue and almost no organic traffic saw maybe 12% improvement. But we’ve never had a migration where PageSpeed scores didn’t dramatically improve. The speed gain is guaranteed by the architecture change; the business impact depends on your traffic, market, and competitive landscape.
What It Actually Costs
The Hyvä license is €1,000. That’s paid directly to Hyvä and gets you the theme for one Magento installation, including one year of updates. Hyvä Checkout is another €500 if you want it. Annual renewal after year one is €250.
Development cost — the bigger number — depends on your store:
| Store Complexity | What That Looks Like | Timeline | Cost Range |
|---|---|---|---|
| Simple | Under 10 extensions, mostly standard design, no crazy checkout customisation | 3–5 weeks | $5K – $10K |
| Mid-range | 10–25 extensions, custom design, maybe multi-store or multi-language | 6–10 weeks | $10K – $20K |
| Enterprise | 25+ extensions, ERP/PIM integrations, complex checkout, B2B features | 10–16+ weeks | $20K – $50K+ |
The biggest cost variable is always extension compatibility. Every incompatible module that needs a custom compatibility layer adds 8–40 dev hours depending on how much frontend code it has. A store with 5 incompatible extensions can easily add $8K–$15K to the project.
Want a quick ballpark? We built a cost calculator on our services page — plug in your extension count and store type and it gives you an estimate in 30 seconds. For a real quote with a fixed price, reach out to us and we’ll go through your store properly.
Common Questions
Ready to migrate?
Free audit — we’ll check your extensions, estimate your timeline, and give you a fixed-price quote.
+1 917 722 7715
+44 2037 698881