How to Install Hyvä Theme in Magento 2

Key Takeaways

• Hyvä Theme is free and open source since v1.4.0 (November 2025)
• Requires Magento 2.4.4 or higher, PHP 8.1+, and Node.js 20+
• Installation takes 8 steps using Composer
• Disable Magento's built-in JS bundling and CSS minification after install
• Create a child theme before customizing anything
• Pages load 4 to 5 times lighter than Luma

TL;DR

Hyvä Theme = A modern Magento 2 frontend built on Tailwind CSS and Alpine.js. Replaces Knockout.js and RequireJS with a stack that loads pages 4 to 5 times faster.

Perfect for: Production stores prioritizing Core Web Vitals, developers tired of Luma's complexity, stores targeting mobile shoppers

Not ideal for: Stores relying on dozens of third-party extensions without Hyvä compatibility modules

What is Hyvä Theme?

Hyvä is a complete frontend replacement for Magento 2. It removes Knockout.js, RequireJS, jQuery, and LESS. In their place: Tailwind CSS for styling and Alpine.js for interactivity.

The result is a frontend that ships around 0.15 MB per product page. Luma ships around 0.9 MB for the same page. If your store struggles with slow page loads, the theme addresses the root cause: frontend bloat.

The core theme became free and open source on November 10, 2025 with version 1.4.0. It uses OSL3 and AFL3 licenses, matching Magento Open Source itself. Commercial products like Hyvä UI (€250 per store), Hyvä Checkout, and Hyvä Enterprise remain paid.

The latest version is 1.4.4, released March 3, 2026. It ships with Tailwind CSS v4, which brings the new Oxide engine written in Rust for faster builds and CSS-first configuration via @theme directives. Other stable features include BFCache, Speculation Rules, and View Transitions. See the full changelog for details.

Prerequisites

Before installing, confirm your environment meets these requirements.

You also need a free Packagist key. Register at hyva.io, then create a key from your account dashboard. Individuals get up to 5 free keys. Agency partners get up to 50.

Check your Magento system requirements match before proceeding.

Step-by-Step Installation

Step 1: Configure Composer Authentication

Add your Packagist key to your project:

composer config --auth http-basic.hyva-themes.repo.packagist.com token YOUR_LICENSE_KEY

Then add the private Packagist repository:

composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/YOUR_PROJECT_NAME/

Replace YOUR_LICENSE_KEY and YOUR_PROJECT_NAME with the values from your portal dashboard. The official getting started guide covers key generation and repository setup in detail.

Step 2: Install the Theme Package

Run a single Composer command to install the theme and all required modules:

composer require hyva-themes/magento2-default-theme

This pulls in the default theme, theme module, and all supporting packages.

Step 3: Run Setup Upgrade

Update the Magento database schema:

bin/magento setup:upgrade

Step 4: Activate the Theme

1. Log into your Magento Admin Panel
2. Go to Content > Design > Configuration
3. Select your store's scope
4. Set the Applied Theme to Hyvä default

Important: Set the theme at the Website level, not just Store View. Setting it at Store View level alone causes frontend rendering issues.

Step 5: Disable Built-in Minification

The theme handles its own asset optimization. Magento's built-in bundling conflicts with it. Run these commands:

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

Step 6: Disable Default Captcha

The theme does not support Magento's built-in Captcha module. Use Google reCAPTCHA v2 or v3 instead:

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

Then configure Google reCAPTCHA through Stores > Configuration > Security > Google reCAPTCHA Storefront.

Step 7: Enable GraphQL Modules

The frontend relies on GraphQL for data fetching. Ensure these modules are enabled:

bin/magento module:enable Magento_GraphQl Magento_CatalogGraphQl \
  Magento_CustomerGraphQl Magento_StoreGraphQl Magento_CmsGraphQl \
  Magento_UrlRewriteGraphQl Magento_SwatchesGraphQl \
  Magento_CheckoutGraphQl Magento_QuoteGraphQl

On Magento 2.4.7 and newer, most GraphQL modules come enabled by default. Verify with:

bin/magento module:status | grep GraphQl

Run bin/magento setup:upgrade again if you enabled new modules.

Step 8: Deploy and Flush Cache

Developer mode:

bin/magento cache:flush

Production mode:

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

Open your storefront. You should see the default theme active.

Create a Child Theme

Never edit the default theme files. Create a child theme for all customizations.

Generate the Theme Directory

app/design/frontend/YourVendor/yourtheme/
├── registration.php
├── theme.xml
└── web/tailwind/
    ├── tailwind.config.js
    └── tailwind-source.css

registration.php

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

theme.xml

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

Build Tailwind CSS

Navigate to your child theme's web/tailwind/ directory:

npm install
npx tailwindcss -o ../css/styles.css --watch

For production builds, add the --minify flag. With Tailwind v4, builds complete faster thanks to the Oxide engine written in Rust.

Activate Your Child Theme

Go back to Content > Design > Configuration and switch to your new child theme at the Website level.

Hyvä vs Luma: Performance Comparison

Real-world benchmarks show clear differences between the two frontends. Test the Hyvä demo store to see live results.

These numbers translate to better Core Web Vitals scores. LCP, FID, and CLS all improve when pages weigh less and execute less JavaScript.

For stores running on managed Magento hosting, the performance gains compound with server-side optimizations like Varnish caching and PHP OPcache.

Common Issues and Fixes

Styles Not Loading After Installation

Flush all caches and redeploy static content:

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

If styles still break, check that the theme is set at Website level in Admin, not just Store View.

Third-Party Extension Compatibility

Not all Magento extensions work with the new frontend out of the box. Luma-dependent extensions need compatibility modules. Check the official compatibility list before installing extensions.

Many popular extensions from vendors like Amasty already offer compatible versions. Check with your extension vendor first.

GraphQL Errors on Frontend

Enable all required GraphQL modules. Missing modules cause blank pages or JavaScript errors:

bin/magento module:status | grep GraphQl

Compare against the list in Step 7 and enable any missing modules.

Tailwind CSS Not Compiling

Verify Node.js version 20 or higher:

node --version

If using nvm, switch to the correct version:

nvm use 20

Then remove node_modules and reinstall:

rm -rf node_modules
npm install

Migrating from Luma to Hyvä

Switching an existing store requires planning. The new frontend uses different template files, layout XML conventions, and JavaScript patterns than Luma.

Key steps:

1. Audit extensions for compatibility before starting
2. Set up a staging environment to test the migration
3. Port custom templates from .phtml files using Knockout.js to Alpine.js equivalents
4. Rebuild checkout customizations if you modified the default checkout
5. Test payment gateways since payment method templates change

The official upgrade and migration guide covers each step in detail. For architecture decisions between frontend approaches, see our Hyvä vs PWA comparison. Explore all available theme features and extensions to plan which commercial add-ons you need.

FAQ

What Magento versions support Hyvä Theme?

The theme requires Magento 2.4.4 or higher. The latest release (1.4.4) supports Magento 2.4.4-p9 through 2.4.8 and newer patch releases.

Is Hyvä Theme free?

Yes. The core theme became free and open source on November 10, 2025 with version 1.4.0. Commercial add-ons like Hyvä UI (€250 per store), Hyvä Checkout, and Hyvä Enterprise remain paid products.

How long does installation take?

On a clean Magento installation, the basic setup takes 15 to 30 minutes. Building a production-ready child theme with custom styles adds several hours depending on design complexity.

Does it work with all Magento extensions?

No. Extensions built for Luma's Knockout.js frontend need compatibility modules. Many popular extensions already offer compatible versions. Check the official compatibility list before purchasing extensions.

Can I use it on Adobe Commerce (Enterprise)?

Yes. The theme supports both Magento Open Source and Adobe Commerce. For B2B features like requisition lists, shared catalogs, and company accounts, you need the paid Enterprise add-on.

What is the difference between Hyvä Theme and Hyvä Commerce?

The Theme is the free, open source frontend. Commerce is a commercial product bundle that includes the Theme plus UI, Checkout, and Enterprise features in one package.

Do I need Node.js for production servers?

No. Node.js is needed on development machines to compile Tailwind CSS. Production servers serve the pre-compiled CSS files. Your build pipeline handles compilation before deployment.

How do I update to a new version?

Update via Composer: run composer update hyva-themes/magento2-default-theme, then bin/magento setup:upgrade and bin/magento cache:flush. Review the upgrade guide at docs.hyva.io for breaking changes between versions.

Does Hyvä improve SEO?

Faster page loads improve Core Web Vitals scores. Google has used CWV as a direct ranking signal since 2021. Lighter pages also reduce bounce rates on mobile. The SEO impact comes from better performance metrics, not from any built-in SEO features.

Can I switch back to Luma after installing?

Yes. Change the theme back in Content > Design > Configuration. Your Luma templates remain in the codebase. The switch is reversible, though custom templates built for the new frontend will not carry over.

Summary

Hyvä Theme replaces Magento's aging Luma frontend with a modern, lightweight stack. Since going open source in November 2025, adoption barriers have dropped to zero for the core theme.

The installation follows standard Composer workflows. The real work starts after: building a child theme, verifying extension compatibility, and porting custom templates from Knockout.js to Alpine.js.

For stores where frontend performance determines conversion rates, the theme delivers measurable improvements. Pages load 4 to 5 times faster with no functional compromises.

Pair it with fast Magento hosting to maximize the speed gains.