How to Migrate Your Magento 2 Store to Hyvä Theme: The Complete Guide

This guide is a full rewrite. It covers what Hyvä is today, what is free and what is not, and a phase-by-phase migration process you can follow whether you are a merchant planning the project or a developer doing the work.

What Has Changed Since 2024

One point is worth stating clearly because it is often misunderstood: a Hyvä migration is a front-end migration. Your products, customers, orders and configuration stay exactly where they are. What changes is the code that renders your storefront.

What Hyvä Is Today

Hyvä started as a lightweight frontend theme for Magento 2 and Adobe Commerce. Today it is a product suite. The theme is a from-scratch frontend that keeps the Magento concepts developers already know (layout XML, blocks, view models and phtml templates) and replaces the heavy parts of Luma (UI components, Knockout, RequireJS and LESS) with Tailwind CSS and Alpine.js. The result is less JavaScript, simpler templates and, for most stores, a clear improvement in Core Web Vitals.

Prices change, so confirm current figures on hyva.io before you budget.

Is Hyvä Really Free? What You Still Pay For

The core theme is free. It is licensed under OSL 3.0 and AFL 3.0, the same family as Magento Open Source, with the code available on GitHub and through free Packagist keys from the Hyvä Portal. Developers can even build and sell their own commercial themes on top of it. Merchants who bought a theme licence before the change keep their premium support and receive Hyvä UI at no extra cost.

Free does not mean the project is cheap. The licence was always a small part of a migration budget. The real cost sits in:

• Extension compatibility. Every extension that ships frontend code needs a Hyvä compatibility module, built by the vendor, the community or you.
• Design and custom code. A bespoke Luma design has to be rebuilt with Tailwind and Alpine.
• Checkout. Payment and shipping extensions that inject checkout UI are the highest-risk area.
• Testing and SEO safeguarding. Skipping these is how migrations lose revenue.
• Optional paid products. Checkout, Commerce, Enterprise and the UI Library.

Should You Migrate? A Practical Decision Guide

Hyvä is a strong fit when:

• You run Luma, Blank or a lightly customised theme and want better Core Web Vitals.
• You want simpler frontend code that is cheaper to maintain.
• Headless or PWA is more than your budget or team can support.
• Your key extensions already have Hyvä compatibility.

Plan more carefully, or think twice, when:

• Your frontend is heavily customised. Lots of custom JavaScript and layout work means a rebuild, not a reskin.
• You rely on niche extensions with no Hyvä support. Budget for compatibility work or replace them.
• You run Adobe Commerce with B2B, Live Search or Product Recommendations. You need Hyvä Enterprise. Check coverage for your exact version before committing.
• Your backend is slow. Hyvä reduces frontend weight. It does not fix poor hosting, a bloated database or a missing full-page cache. Measure server response time first.

Start with a baseline of real-user data, not opinions. The decision should rest on your current Core Web Vitals, frontend defects, release speed, extension debt and checkout requirements.

Phase 1: Audit and Plan

1. Platform and environment

Each new Magento release raises the PHP requirements. Magento 2.4.9, for example, supports PHP 8.4 and 8.5 and drops PHP 8.2 and MySQL 8.0. Each 2.4.x line receives regular support for about three years and no security patches after that, so a store on an unsupported line should be upgraded regardless of the theme project. Confirm current versions and dates on Adobe's lifecycle page.

Our rule: never change the platform version and the frontend in the same release. Upgrade Magento first, let it stabilise, then migrate the theme. Before moving to a new Magento release, check the Hyvä release notes and your extension vendors for support.

2. Performance and SEO baseline

Record these before you touch anything:

• Core Web Vitals field data from Search Console and CrUX, plus Lighthouse results for six templates: home, category, product, cart, checkout and search.
• Conversion rate, add-to-cart rate and checkout drop-off.
• Your top landing pages by organic traffic.

Without a baseline you cannot prove the project worked. Field data takes about four weeks to reflect a change, so plan for that delay when you report results.

3. Extension audit

List every installed module, then classify each one:

Check Hyvä's public Compatibility Module Tracker on gitlab.hyva.io and your vendors' product pages. Many vendors now list Hyvä support.

4. Custom code and content audit

Inventory your custom theme (layout XML, templates, LESS, requirejs-config and JavaScript), CMS pages and blocks (especially Page Builder content and widgets), email templates and any custom pages.

5. Decide your scope

• Theme only, or Hyvä Commerce if you want Hyvä CMS and the admin tools.
• Hyvä Enterprise, if you run Adobe Commerce features.
• Checkout path. Launch with your current checkout and move later, or launch with Hyvä Checkout. Because it can be enabled per store view, you can roll it out gradually.

Phase 2: Build a Safety Net

Since a Hyvä migration does not move data, you do not need a data export and import. What you need instead:

• A staging copy of production (database and media) with customer data masked.
• Your code in Git on a dedicated migration branch.
• A CI pipeline that builds the Tailwind CSS bundle and deploys to staging.
• A database snapshot and a written rollback plan before go-live.

Phase 3: Install Hyvä

Work on staging. These steps follow Hyvä's official getting-started guide.

Step 1. Get a key. Register in the Hyvä Portal at hyva.io and create a free Packagist key.

Step 2. Configure Composer.

composer config --auth http-basic.hyva-themes.repo.packagist.com token YOUR_KEY
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/YOUR_PROJECT_NAME/

Step 3. Install the theme.

composer require hyva-themes/magento2-default-theme
bin/magento setup:upgrade

Step 4. Activate it. In the Magento admin go to Content > Design > Configuration and select hyva/default. Always set a theme at the Website level as well. If the Website level is left on No Theme, the storefront breaks. It does not matter which theme sits at Website level, as long as one is set.

Step 5. Disable the legacy captcha. Hyvä does not support Magento's old captcha. Use Google ReCaptcha V3 invisible, V2 invisible or V2 checkbox instead.

bin/magento config:set customer/captcha/enable 0

Step 6. Turn off Magento's minification and bundling for Hyvä store views. They add overhead without benefit.

bin/magento config:set dev/template/minify_html 0
bin/magento config:set dev/js/merge_files 0
bin/magento config:set dev/js/enable_js_bundling 0
bin/magento config:set dev/js/minify_files 0
bin/magento config:set dev/js/move_script_to_bottom 0
bin/magento config:set dev/css/merge_css_files 0
bin/magento config:set dev/css/minify_files 0

If some store views still run Luma, keep these settings on for those store views.

Step 7. Enable the required GraphQL modules. Hyvä uses parts of Magento's GraphQL API. Stores that ran Luma often have unused GraphQL modules disabled. Check the modules Hyvä lists (for example Magento_CatalogGraphQl, Magento_CustomerGraphQl, Magento_QuoteGraphQl, Magento_SalesGraphQl and Magento_WishlistGraphQl) with bin/magento module:status.

Step 8. Verify. In developer mode the Hyvä storefront appears straight away (flush the cache if needed). In production mode, run bin/magento setup:static-content:deploy first.

Install from Packagist in CI and production pipelines. Direct GitLab access is for Hyvä partners and contributors, and GitLab availability is not guaranteed.

Phase 4: Build Your Child Theme

Never edit the default Hyvä theme directly. Create a child theme under app/design/frontend/YourVendor/yourtheme so upgrades stay painless.

• Put your brand colours, fonts and spacing in the Tailwind configuration so a design change cascades everywhere.
• Run the Tailwind watcher on development machines. In production you must ship a pre-built, minified styles.css.
• Build the CSS on a development, staging or CI machine, never on the production server. Installing Node.js on production adds avoidable security risk.
• Current Hyvä versions use npm run build. Older 1.1.x releases used build-prod.
• Consider the Hyvä UI Library for accessible, ready-made components that speed up design work. Hyvä's docs also cover fonts, localization, accessibility and email styling.

Phase 5: Make Extensions and Custom Code Compatible

Modules written for Luma need a compatibility module that re-implements the parts that do not work in a Hyvä storefront. For many modules this is straightforward. Work through your audit list in priority order, starting with the extensions your revenue depends on.

The typical conversions are:

• data-mage-init and require() scripts become small inline scripts in the phtml template, registered with Alpine.
• x-magento-template blocks become Alpine x-for loops.
• jQuery data() becomes native dataset, and Underscore and jQuery helpers become plain JavaScript.
• Luma LESS becomes Tailwind classes.

A minimal example of the pattern:

<script>
    function initMyComponent() {
        return {
            open: false,
            toggle() { this.open = !this.open }
        }
    }
    document.addEventListener('alpine:init', () => {
        Alpine.data('initMyComponent', initMyComponent)
    });
</script>

After you install a vendor's compatibility package or register your own module, regenerate Hyvä's configuration with bin/magento hyva:config:generate and rebuild the Tailwind CSS so the module's classes are included. Missing styles after adding a module are almost always a missed rebuild.

Hyvä's documentation also covers a Luma theme fallback for pages you have not converted yet. Use it as a short-term bridge only, because fallback pages carry Luma's heavier JavaScript and weaken the performance gains.

Phase 6: Content, Menus, Emails and Checkout

CMS content. Pages and blocks built with Page Builder often need restyling, so review each one. Hyvä CMS, part of Hyvä Commerce, is a component-based CMS with a live visual editor that lets merchants update pages without a developer for every change.

Navigation and emails. Hyvä Commerce adds a Menu Builder and a visual editor for transactional emails and newsletters. Without it, you restyle the default email templates in your child theme.

Checkout. Hyvä Checkout replaces Magento's checkout with a server-rendered checkout built on Magewire. Payment and shipping extensions need versions that work with it. Test every payment method with your gateway's sandbox, including cards, 3-D Secure, wallets, buy-now-pay-later and cash on delivery, plus coupons, tax rules, guest and registered checkout, and virtual or downloadable products.

Phase 7: Test Everything

A migration should not change your URLs. Keep them identical, and confirm structured data and tracking events fire exactly as before.

Phase 8: Deploy and Go Live

Production deployment has three steps: build the minified stylesheet, run Magento's static content deploy, and transfer the compiled files.

# 1. Build the Tailwind CSS (on a dev or CI machine)
cd app/design/frontend/YourVendor/yourtheme/web/tailwind
npm ci --ignore-scripts
npm run build

# 2. Deploy static content, skipping what Hyvä does not need
bin/magento setup:static-content:deploy -j 2 -f --area=frontend --no-parent --no-less --no-js-bundle --no-html-minify --theme=YourVendor/yourtheme en_US

# 3. Transfer pub/static to production, then flush caches
bin/magento cache:flush

In CI, npm ci gives reproducible builds, and --ignore-scripts protects against supply chain attacks from package lifecycle scripts. Hyvä's documentation also covers Adobe Commerce Cloud and Capistrano deployments.

Go-live checklist

1. 1
   Freeze content changes and non-essential deployments.
2. 2
   Deploy the final build and activate the Hyvä theme on the target store views, with a theme also set at Website level.
3. 3
   Flush Magento, Varnish and CDN caches.
4. 4
   Run a smoke test: browse, search, add to cart, check out with a live payment, confirm the order email.
5. 5
   Check analytics, tag manager events and the sitemap.
6. 6
   Monitor error logs and server load closely for the first 48 hours.

Switching themes is an admin configuration change, not a DNS change. To reduce risk, launch on one store view or country first and expand once it is stable.

Rollback plan. Keep your previous theme assets deployed. If something critical breaks, switch the design configuration back to the previous theme and flush caches.

Phase 9: After Launch

• Monitor. Track Core Web Vitals in Search Console, conversion rate and checkout completion against your baseline. Expect field data to settle over about four weeks.
• Keep Hyvä updated. Follow Hyvä's upgrade guide and security advisories, and update on a regular schedule rather than waiting for a problem.
• Keep Magento patched. Adobe ships security patches on a regular schedule, so build patching into your routine.
• Use the community. Hyvä has an active Slack community, technical support and a certification program for developers.

Common Problems and Fixes

Frequently Asked Questions

Is Hyvä Theme free now? Yes. Since 10 November 2025 the Hyvä Theme is open source and free. Hyvä Checkout, Commerce, Enterprise and the UI Library remain paid products.

Do I need Hyvä Commerce? No. The theme works on its own. Choose Commerce if you want Hyvä CMS, the admin tools and Hyvä Checkout in one bundle.

Does Hyvä work with Adobe Commerce? Yes, through Hyvä Enterprise, which adds compatibility with Adobe Commerce, the B2B suite and Adobe services such as Live Search and Product Recommendations. Check coverage for your version.

Will my extensions work? Backend-only extensions usually do. Extensions with frontend code need a Hyvä compatibility module. Check the Compatibility Module Tracker and ask your vendors.

Will migrating hurt my SEO? Not if you keep URLs, canonical tags, structured data and redirects intact and test them before launch. Lighter pages generally help Core Web Vitals.

Can I run Luma and Hyvä at the same time? Yes. Themes are assigned per store view, so you can migrate gradually. Keep Magento's minification settings on for the Luma store views.

How is Hyvä different from headless or PWA? Hyvä keeps server-rendered Magento templates and adds Tailwind and Alpine.js instead of a separate single-page application. Hyvä positions this as faster and cheaper to build than most SPAs.

Conclusion

With the theme now free, Hyvä is a far easier decision than it used to be. The technology is not the hard part. The work is in the audit, extension compatibility, checkout testing and protecting your SEO. Plan those carefully, migrate in a staging environment, launch gradually, and measure against a baseline.

Planning a Hyvä migration? Wisenetic's Magento team can audit your extensions and custom code and give you a realistic estimate. Contact us at info@wisenetic.com.