Luma to Hyvä Migration Plan: Audit, Phases and Launch

Moving a live Magento store from Luma, or a custom theme built on Luma, to Hyvä is a rebuild of the frontend, not an upgrade. The backend stays, but every template with JavaScript, every LESS file and every frontend extension needs attention. Projects that go well treat it as a planned migration with an audit, clear phases and a rollback path. This is the plan I follow, in the order I follow it.

Phase 1: audit before estimating

Do not estimate a Hyvä migration from the homepage. The cost sits in the details, and you only find them with an audit. I collect four lists.

Extensions with storefront output

List every enabled module that is not core Magento:

bin/magento module:status --enabled | grep -v '^Magento_' | grep -v '^PayPal_'

For each one, record whether it adds anything to the storefront (templates, JavaScript, CSS, checkout components), which pages it affects, and whether the vendor ships Hyvä support. Admin only and integration modules can be ignored for the frontend estimate. This is also the moment to remove modules nobody uses anymore. An extension audit usually pays for itself here, because every removed module is one less compatibility task.

Theme customizations

List every template override, layout file, JavaScript file, mixin and LESS file in the current theme and in custom modules. A quick way to size it:

find app/design/frontend -name '*.phtml' | wc -l
find app/design/frontend app/code -path '*view/frontend*' -name '*.js' | wc -l
find app/design/frontend app/code -path '*view/frontend*' -name 'requirejs-config.js'

The count of JavaScript files and mixins is a better predictor of effort than the count of templates. Each mixin represents behavior that has to be understood and rebuilt.

Checkout

List payment methods, shipping methods with custom UI, and every checkout customization (fields, steps, validations, address autocomplete). Checkout is its own decision, covered in the next phase.

Content

Find out how content is managed: CMS pages and blocks, widgets, Page Builder, sliders from extensions. Count the Page Builder content types in use and the CMS blocks with inline styles or scripts. Content that looked fine on Luma will need restyling, and inline jQuery in CMS blocks will stop working.

Phase 2: decisions

With the audit done, make three decisions explicitly and write them down.

1. Checkout. Launch with a Luma checkout fallback, or with Hyvä Checkout, or another checkout. Launching the theme first with the fallback and moving checkout later is usually lower risk. The trade-offs are in the Hyvä Checkout overview.
2. Each extension. Vendor compatible version, existing community compat module, your own compat module, Luma fallback for its routes, or removal. See Hyvä compatibility modules for how each option works.
3. Design scope. A like for like port of the current design, or a redesign. Combining migration and redesign is common, but it doubles the number of things that can be argued about. If the design is changing, freeze it before development starts.

Also check licensing for Hyvä and any Hyvä related products you plan to use. Terms have changed over time, so read the current ones on hyva.io rather than relying on older articles or estimates.

Phase 3: foundation

• Install Hyvä and create a child theme, as in the Hyvä theme setup guide.
• Set up the Tailwind build in CI so compiled CSS is produced before static content deploy.
• Configure brand colors, fonts and base component styles (buttons, inputs, headings) in the Tailwind config first. Every page built later benefits from it.
• Assign the new theme to a store view on staging only. Production keeps Luma until launch.

Because the theme is assigned per store view in the design configuration, the same code base can serve Luma in production and Hyvä on staging during the whole project. That makes it possible to keep shipping backend fixes to production while the frontend is being rebuilt.

Phase 4: rebuild page by page

Work in the order customers see the site, and finish each area before moving on.

1. Global elements: header, navigation, mini cart, search box, footer, cookie notice, messages. These appear on every page and expose customer data section handling early.
2. Category pages: product tiles, layered navigation, sorting, pagination, swatches.
3. Product pages: every product type you sell. Configurable products with swatches and bundle products usually take the longest.
4. Cart page and any cart extensions such as gift wrapping or cross sells.
5. Customer account: login, registration, dashboard, orders, addresses, wishlist, and extension pages in the account area.
6. CMS pages and content, including Page Builder content types.
7. Checkout, according to the decision from phase 2.

For each area, rebuild custom behavior with Alpine.js instead of porting jQuery line by line. A lot of Luma frontend code exists to work around RequireJS loading order and Knockout bindings. It does not need to exist on Hyvä. Reuse the backend parts: view models, blocks and controllers usually carry over unchanged.

Phase 5: SEO and analytics parity

A frontend rebuild can quietly break things search engines and marketing depend on. Before launch, compare old and new for:

• URLs. They should not change. A theme migration is not the time to change URL structure.
• Title tags, meta descriptions, canonical tags, robots meta and hreflang on each page type.
• Structured data for products, breadcrumbs and organization. See structured data for Magento 2.
• Heading structure and the visible text on category and product pages.
• Analytics and tag manager events: page views, view item, add to cart, begin checkout, purchase. Luma based tracking modules often push events from Knockout or jQuery code that no longer runs.

Crawl both versions with the same crawler and diff the results. It is the fastest way to find a missing canonical or a broken template on a page type nobody tested by hand.

Phase 6: testing

• Functional tests of each page type on desktop and mobile, as guest and logged in.
• Full order placement with every payment method and every shipping method.
• Full page cache behavior: mini cart, customer name, messages and prices for customer groups on cached pages.
• Performance measured on staging with production data, compared to the Luma baseline you recorded before starting.
• Accessibility basics: keyboard navigation in menus and modals, focus states, labels on form fields.

Phase 7: launch and rollback

Launch is a configuration change: assign the Hyvä child theme to the production store views, deploy static content, and flush caches.

bin/magento setup:static-content:deploy -f --theme Acme/hyva --theme Magento/luma en_US
bin/magento cache:flush

Deploy static content for both themes during the first weeks. If the Luma checkout fallback is in use, you need the Luma theme anyway. If something serious goes wrong after launch, rollback is assigning the old theme back to the store view and flushing caches. Keep the old theme in the code base and working until you are confident, and agree in advance who can make that call.

Launch early in the week, outside sales peaks, with developers available. Watch error logs, conversion rate, add to cart rate and checkout completion daily for the first two weeks. A drop in one of these after a frontend change is usually a broken interaction on a specific page type, and the analytics will tell you which one.

After launch

• Remove modules that were disabled during the migration and are no longer needed.
• Plan the retirement of fallback routes, if any.
• Remove the old theme once rollback is no longer a realistic option.
• Document how the Tailwind build, compat modules and the hyva-themes.json generation fit into the deploy, so the next developer does not have to rediscover it.

The migration is also a good point to set a performance budget. Hyvä starts fast, but third party scripts, large images and tag manager containers can bring a store back to Luma level speeds within months. Track Core Web Vitals from field data after launch and treat regressions as bugs.

FAQ

Can I migrate to Hyvä one page type at a time on production?

Not cleanly, because the theme is assigned per store view, not per page. The usual approach is to build the whole storefront on staging and switch the store view at launch, with Luma fallback only for specific routes such as checkout.

What makes a Hyvä migration expensive?

Mostly third party extensions with storefront JavaScript and custom theme behavior built in jQuery or Knockout. The number of templates matters less than the amount of frontend JavaScript.

Do URLs change when moving to Hyvä?

They should not. Hyvä is a theme, so URL rewrites stay the same. Check canonical tags, structured data and meta tags on each page type before launch.

How do I roll back if the launch goes wrong?

Assign the previous theme back to the store view in the design configuration, make sure its static content is deployed, and flush caches. Keep the old theme in the code base until you are confident.

I am available for freelance Magento and Hyvä migration work. If you are planning a move from Luma, get in touch.