Migrating from Luma to Hyvä: Common Pitfalls
Migrating from Luma to Hyvä: Common Pitfalls
~8 Min. Lesezeit Zuletzt aktualisiert am August 9, 2026
Migrating an existing Luma project to Hyvä isn't a simple theme switch - it's practically a frontend rebuild. This chapter collects the most important pitfalls for developers facing this transition.
No 1:1 template mapping
A Luma .phtml template can't simply be copied and lightly adjusted - Knockout bindings (data-bind), ko_template references, and RequireJS module references simply have no equivalent in Hyvä. Realistically, every customized template has to be rewritten from scratch following Hyvä conventions (chapters 6-9), not run through a migration script.
Auditing custom Luma extensions and third-party modules
Before migrating, it's worth taking stock: which custom Luma templates/blocks exist, and which third-party extensions bring their own frontend along? Not every Magento module supports Hyvä out of the box - some need a separate Hyvä compatibility module (often provided by the Hyvä community or the vendor itself), others need to be rebuilt for Hyvä entirely.
Achtung: A common migration mistake: activating Hyvä in production without first checking whether business-critical third-party extensions (payment providers, shipping calculators, custom checkout extensions) even have a Hyvä version. In the worst case, that leads to a broken checkout in production.
Incremental migration vs. "big bang"
A complete rebuild in a single deployment is risky and hard to test. An incremental migration is often more sensible: first set up a staging environment with Hyvä alongside the production Luma site, migrate and test page by page (home page, category page, product page, checkout), and only switch over completely at the end.
Rethinking CSS and JavaScript from scratch
LESS files from Luma can't be automatically translated into Tailwind classes - at its core, this is a complete redesign of the styling, not a migration in the technical sense. The upside: it's the ideal opportunity to leave grown, unwieldy LESS code behind and start fresh with a clean, consistent design token structure (chapter 12).
Building team knowledge before migration starts
Since Hyvä development differs fundamentally from Luma development (no Knockout, no UI components, Tailwind instead of LESS, Alpine instead of jQuery), it's worth having the development team actually work through this series' fundamentals (blocks 1-4) before the actual migration begins - time pressure during an ongoing migration is about the worst moment to learn new concepts for the first time.
Tipp: A good first migration project to practice on: build a single, independent page (like the team page from chapters 17-22 in this series) entirely fresh in Hyvä, before tackling business-critical pages like checkout or the product page.