How to Install the Hyvä Theme in Magento 2: The Complete 2026 Guide

If you build or maintain Magento stores, 2026 is the year the Hyvä conversation stopped being "should we?" and became "how fast can we?". As of November 2025, the Hyvä theme is free and open source — the paid license that used to gate it is gone. The single biggest barrier to a modern Magento front end just disappeared.

This guide walks through installing Hyvä in Magento 2 the way we'd do it on a real project: verified Composer commands, a clean child theme so your work survives updates, a realistic path for migrating off Luma, the hosting stack that actually makes the performance numbers real, and the handful of issues that trip up almost everyone on their first install.

01What Hyvä actually is

Hyvä (Swedish for "good") is a complete replacement for Magento's default Luma front end. Instead of the legacy stack of Knockout.js, RequireJS, LESS, and a mountain of jQuery, Hyvä rebuilds the storefront on two modern, lightweight tools:

• Tailwind CSS — a utility-first CSS framework that ships only the styles you actually use.
• Alpine.js — a tiny (~15 KB) reactive JavaScript framework for interactivity, with no build-step tax on the browser.

Crucially, Hyvä is not a headless or PWA rewrite. It keeps Magento's native, server-rendered architecture — the same .phtml templates, layout XML, and blocks you already know — so you get a dramatic performance jump without throwing away the platform's SEO strengths or committing to a separate front-end application. For most merchants, that's the sweet spot: modern speed, familiar Magento.

02Why it's so much faster

The performance gap between Hyvä and Luma isn't marginal — it's an order of magnitude, and it comes down to how much the browser has to download and execute. Luma ships hundreds of kilobytes of JavaScript before a shopper can do anything. Hyvä ships a fraction of that.

Three things drive the difference: Hyvä sends roughly 80–90% less front-end code, it replaces Knockout+RequireJS with Alpine's ~15 KB, and Tailwind's build step purges unused CSS so the stylesheet stays tiny. Fewer bytes and less JavaScript execution translate directly into faster Largest Contentful Paint, better Core Web Vitals, and — in practice — higher conversion on mobile.

03License & cost in 2026

Here's the current lay of the land, so you know exactly what you're getting for free and where money still comes into play.

04Before you start

Hyvä runs on top of a standard Magento install, but check these off first. A mismatch here is the most common reason an install "doesn't work".

05Installing Hyvä — 8 steps

On a prepared server this takes 15–30 minutes. Run every bin/magento command from your Magento root directory.

Register at hyva.io, open your account dashboard, and generate a free packagist.com authentication key. Individual accounts get several keys; agency partners get many more. Copy your key and your project name — you'll need both in the next step.

Point Composer at Hyvä's private Packagist repository and store your key. Replace YOUR_KEY and YOUR_PROJECT_NAME with your real values.

# Store your Hyvä auth key
composer config --auth http-basic.hyva-themes.repo.packagist.com token YOUR_KEY

# Register the private Hyvä repository
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/YOUR_PROJECT_NAME/

Pull in the default Hyvä theme package and let Magento register the new modules.

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

In the Magento admin, go to Content → Design → Configuration, edit your store's scope, and set the Applied Theme to Hyvä default. Save.

Hyvä manages its own optimized assets. Magento's built-in JS/CSS merging and bundling will fight it and can break the front end, so turn them off.

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

Magento's default CAPTCHA relies on Luma-era JavaScript and can silently break Hyvä forms (including checkout). Disable it and use Google reCAPTCHA v2/v3 instead.

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

Hyvä uses GraphQL for several interactive pieces (mini-cart, search, etc.). Confirm the modules are enabled — on 2.4.7+ they are by default.

bin/magento module:status | grep GraphQl

Finally, compile and deploy, then flush the cache to see Hyvä live.

bin/magento setup:static-content:deploy
bin/magento cache:flush

06Create a child theme (don't skip this)

Never customize the default Hyvä theme directly — the next update will overwrite your work. Instead, create a child theme that inherits from Hyvä and holds all your changes. Here's the minimal structure:

The key file is theme.xml, where you declare Hyvä as the parent:

<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>MagedIn Store</title>
    <parent>Hyva/default</parent>
</theme>

And registration.php, which registers the theme with Magento:

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::THEME,
    'frontend/MagedIn/store',
    __DIR__
);

Then install Tailwind's dependencies and compile your CSS. Use --watch while developing and --minify for production:

# from your child theme's web/tailwind directory
npm install
# development: rebuild on change
npx tailwindcss -o ../css/styles.css --watch
# production: minified build
npx tailwindcss -o ../css/styles.css --minify

Set your child theme as the Applied Theme in the admin (same place as Step 4), and from here on, every template override, Tailwind tweak, and component lives in MagedIn/store — untouched by Hyvä updates.

07Migrating from Luma

If you're moving an existing store, the theme install is the easy part. The real work is porting customizations. The mental shift is Knockout.js → Alpine.js: declarative reactivity moves from separate JS files into small, readable attributes right on your markup.

The pattern, side by side

Here's a simple "Add to Cart" button. First the Luma/Knockout way:

<button data-bind="click: addToCart, attr: { disabled: !inStock() }">
    <span data-bind="text: buttonLabel"></span>
</button>

<script>
define(['ko'], function(ko) {
    return {
        inStock: ko.observable(true),
        buttonLabel: ko.observable('Add to Cart'),
        addToCart: function() { /* logic */ }
    };
});
</script>

And the same thing in Hyvä with Alpine — no separate module, no RequireJS, just the component declared inline:

<div x-data="{ inStock: true, buttonLabel: 'Add to Cart' }">
    <button @click="addToCart()" :disabled="!inStock">
        <span x-text="buttonLabel"></span>
    </button>
</div>

A sane migration order

1. Audit your extensions first. Check every third-party module against Hyvä's compatibility registry before you commit to a timeline (more on this below).
2. Work in staging. Never migrate straight to production; test every page type.
3. Port templates from Knockout to Alpine, page type by page type.
4. Rebuild checkout customizations in Alpine, or adopt Hyvä Checkout.
5. Test every payment gateway with a real test transaction before go-live.
6. Validate performance on production-like hardware — numbers from a laptop don't count.

08Extension compatibility

This is where migrations succeed or stall. Because Hyvä replaces the front end, any extension that renders storefront UI needs a Hyvä-compatible version — its Luma templates won't just work. Three outcomes for each extension:

• Native Hyvä support — the vendor ships a Hyvä-ready module. Ideal.
• A compatibility module — a bridge package (often via the Hyvä compatibility registry or the vendor) adapts the extension. Budget roughly $50–$300 each.
• No support — you rebuild the front end yourself, or replace the extension.

09Hosting & the stack that makes it real

Hyvä makes the front end fast, but a slow backend will still make you wait. To actually hit those 90+ Lighthouse scores, the server stack has to keep up. This is the setup we target:

In short: PHP 8.4-FPM with enough workers, Redis 7.2 or Valkey 8 for sessions and backend cache, Varnish 7.7 for full-page caching, OpenSearch 3 for search, a CDN for static assets, and HTTP/2 or HTTP/3 enabled. Get this right and Hyvä's front-end wins actually reach the shopper.

10Common issues & fixes

Styles aren't loading / the store looks unstyled

Usually stale static assets or a wrong theme scope. Clear and redeploy:

bin/magento cache:flush
rm -rf pub/static/frontend/*
bin/magento setup:static-content:deploy

Then confirm the theme is applied at Website scope, not just Store View.

GraphQL errors

Confirm the GraphQL modules are enabled, then re-run setup:

bin/magento module:status | grep GraphQl
bin/magento setup:upgrade

Tailwind CSS won't compile

Almost always a Node version mismatch. Hyvä needs Node 20 or 22 LTS:

node --version        # need v20.x or v22.x
nvm use 20            # switch with nvm if needed
rm -rf node_modules && npm install

An extension renders broken HTML

It doesn't have a Hyvä-compatible front end. Check the Hyvä compatibility registry and install the required compatibility module, or replace the extension.

Checkout fails silently

The usual culprit is the legacy CAPTCHA (Step 6). Disable Magento's default CAPTCHA and install Google reCAPTCHA instead.

11Frequently asked questions