If you’ve been running a Magento store on Luma or Blank theme, you’ve likely felt the frustration of slow page loads, complex frontend templating, and bloated JavaScript. The Magento Hyvä theme was built precisely to solve those problems — and store owners and developers who’ve made the switch rarely look back.
This guide walks you through the complete Hyvä theme installation on Magento 2 from licensing and server requirements to activating the theme, building a child theme, and resolving the most common issues. Whether you’re a developer setting this up for a client or a store owner working with a Hyvä theme development team, this resource gives you everything you need.
Revenue focused Grow Your Magento Revenue by 30%!
Grow your Shopify revenue by up to 30% with lightning-fast checkout and smart conversion tools.
What is the Hyvä Theme for Magento 2?
Hyvä (pronounced “hoo-vah,” Finnish for “good”) is a frontend theme framework for Magento 2 that replaces the default RequireJS/KnockoutJS/jQuery stack with Alpine.js and Tailwind CSS. Released by Dutch developer Willem Wigman in 2021, it has grown into one of the most widely adopted frontend solutions in the Magento ecosystem.
Here’s why the Magento 2 Hyvä theme has become the industry standard for performance-first stores:
- Google Lighthouse scores of 90–100 out of the box, compared to 20–40 on Luma
- Zero RequireJS, eliminating complex dependency chains
- Tailwind CSS utility-first styling enables faster and more consistent frontend customization
- Alpine.js replaces KnockoutJS, providing a lightweight reactive UI
- Dramatically smaller JavaScript bundle sizes, often up to 10x smaller than Luma
- Faster time-to-first-byte and improved Core Web Vitals, critical for SEO performance
- Cleaner and more maintainable codebase for Hyvä theme developers
Prerequisites Before You Install the Hyvä Magento Theme
Before running a single command, make sure the following are in place.
Magento Version Compatibility
The magento hyva theme supports Magento Open Source and Adobe Commerce. The current compatibility matrix is:
System Requirements :
- Magento CE 2.4.4-p9, 2.4.5-p8, 2.4.6-p7, 2.4.7-p1 or higher
- A valid license for Hyvä Themes (https://hyva.io/license)
- For licensees: A Private Packagist Key
- For partners: Access to Hyvä GitLab
- PHP 7.4, 8.1, 8.2, 8.3, or 8.4
Always check the official Hyvä changelog at hyva.io for the latest version support matrix before proceeding.
Server & PHP Requirements
- PHP: 8.1, 8.2, or 8.3 (PHP 8.3 recommended for Magento 2.4.7+)
- Composer: Version 2.x (Composer 1.x is not supported)
- Node.js: 16+ (required for Tailwind CSS compilation)
- NPM or Yarn for frontend build tooling
- Standard Magento 2 server stack: MySQL 8.0+, Elasticsearch or OpenSearch, Redis (optional but recommended
What is Price of Hyvä License?
For Licensees , Please refer to the following link.
A single license covers one production domain plus unlimited staging/development environments. Agency licenses are available for Hyvä theme development companies working on multiple client projects.
Important: Never use nulled or cracked versions of Hyvä. Beyond the obvious legal risk, they lack security updates and official compatibility patches.
Create Your Hyvä Account and Get Composer Credentials
After purchasing:
- Log in to your Hyvä portal at hyva.io
- Navigate to Licenses and create a new license for your domain
- Go to API Tokens and generate a Composer token
- Note your license key, as it will be required during installation
How to install Hyvä Themes in Magento 2.4.x
Step 1: Add the Hyvä Composer Repository
On your server (or local development environment), navigate to your Magento 2 root directory and run:
composer config repositories.hyva-themes composer
https://packages.hyva.io/dist/
When prompted for authentication, enter:
- Username: Your Hyvä account email
- Password: The API token you generated in the portal
To avoid being prompted every time, you can store credentials directly:
composer config http-basic.packages.hyva.io your@email.com YOUR_API_TOKEN
This writes the credentials to your auth.json file. Make sure this file is in .gitignore and never committed to version control.
Step 2: Require the Hyvä Theme Package
With the repository configured, install the core Hyvä theme packages:
composer require hyva-themes/magento2-default-theme
This installs the following key packages:
- hyva-themes/magento2-theme-module — The core Hyvä module
- hyva-themes/magento2-default-theme — The base Hyvä frontend theme
- hyva-themes/magento2-reset-theme — A reset base that sits below the default theme
- hyva-themes/magento2-icons — HeroIcons integration
Composer will pull all dependencies automatically. This step may take a few minutes depending on your connection speed.
Step 3: Enable the Hyvä Modules
Once Composer finishes, register and enable the new modules in Magento:
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:clean
php bin/magento cache:flush
Run these commands in sequence. The setup:upgrade command registers all new modules and updates the database schema. The setup:di:compile command regenerates dependency injection configurations.
Pro tip for production stores: Always run setup:static-content:deploy with your specific locale flags to avoid deploying unnecessary locales. For example: php bin/magento setup:static-content:deploy en_US -f
Step 4: Assign the Hyvä Theme in the Admin Panel
- Log in to your Magento 2 Admin Panel
- Go to Content → Design → Configuration
- Click Edit next to the store view you want to update
- Under Applied Theme, select Hyvä Default from the dropdown
- Click Save Configuration
- Flush the cache using: php bin/magento cache:flush
At this point, the base Hyvä theme is active in your store. If you visit the frontend, you’ll see the default Hyvä layout — clean, fast, and minimal.
Step 5: Configure Your Hyvä License Key
The Hyvä license module validates your key to ensure compliance. To configure it:
- In Admin, go to Stores → Configuration → Hyvä Themes → License
- Enter your License Key from the Hyvä portal
- Set Production Domain to your live store URL
- Save the configuration and flush the cache
Alternatively, you can set it via environment variable or env.php — useful for CI/CD pipelines:
// In app/etc/env.php
'system' => [
'default' => [
'hyva_theme_license' => [
'license_key' => 'YOUR_LICENSE_KEY'
]
]
]
Step 6: Create a Hyva Child Theme (Strongly Recommended)
Never customize the base Hyvä theme directly. Any Composer update will overwrite your changes. Instead, create a Hyvä child theme — this is the professional approach taken by every reputable Hyvä theme development company.
6.1 Create the Theme Directory Structure
mkdir -p app/design/frontend/YourVendor/hyva-child/web/tailwind
mkdir -p app/design/frontend/YourVendor/hyva-child/Magento_Theme/layout
6.2 Create theme.xml
<!-- app/design/frontend/YourVendor/hyva-child/theme.xml -->
<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
<title>YourVendor Hyvä Child</title>
<parent>Hyva/default</parent>
</theme>
6.3 Create registration.php
<?php
// app/design/frontend/YourVendor/hyva-child/registration.php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(
ComponentRegistrar::THEME,
'frontend/YourVendor/hyva-child',
__DIR__
);
6.4 Set Up Tailwind CSS
Copy the Tailwind config from the parent theme as your starting point:
cp vendor/hyva-themes/magento2-default-theme/web/tailwind/tailwind.config.js \
app/design/frontend/YourVendor/hyva-child/web/tailwind/tailwind.config.js
cp vendor/hyva-themes/magento2-default-theme/web/tailwind/package.json \
app/design/frontend/YourVendor/hyva-child/web/tailwind/package.json
Install Node dependencies and compile CSS:
cd app/design/frontend/YourVendor/hyva-child/web/tailwind
npm install
npm run build-prod
6.5 Apply the Child Theme
Copy the Tailwind config from the parent theme as your starting point:
- In Admin, go to Content → Design → Configuration
- Switch the applied theme from Hyvä Default to YourVendor Hyvä Child
- Save the configuration and flush the cache
Step 7: Deploy and Verify
Run the full deploy sequence one more time with your child theme active:
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy en_US -f
php bin/magento cache:flush
Then verify your installation by:
- Visit the storefront and confirm the Hyvä layout loads correctly
- Open browser DevTools → Network tab and verify no RequireJS bundles are loading
- Run a Google PageSpeed Insights test and check for improved performance scores over Luma
- Check Magento Admin → System → Index Management to ensure all indexes are valid
Step 8: Hyvä Compatibility Modules for Third-Party Extensions.
This is where magento 2 hyva theme installations often get tricky. Magento extensions built for Luma use KnockoutJS templates (.html files with data-bind attributes) that do not render in Hyvä.
To make third-party extensions work with Hyvä, you need compatibility modules. The Hyvä ecosystem provides several options:
Official Hyvä Compatibility Modules
| Extension | Compatibility Package |
|---|---|
| Hyva Extension Development | Check hyva-themes/magento2-compat-module-fallback |
| Checkout (default) | hyva-themes/magento2-hyva-checkout (separate license) |
| GraphQL/PWA | Use Hyvä’s REST-based approach instead |
The Hyvä Compatibility Fallback Module
For extensions without a dedicated Hyvä compatibility layer, the fallback module allows Luma-style components to be rendered inside an iframe within the Hyvä page. This is not ideal for performance but keeps the store functional while you source or build proper compatibility.
composer require hyva-themes/magento2-compat-module-fallback
php bin/magento setup:upgrade
php bin/magento cache:flush
What is the difference between Hyvä Checkout and Magento default checkout?
| Feature | Magento Default Checkout | Hyvä Checkout |
|---|---|---|
| Technology | KnockoutJS-based | Hyvä-native (Alpine.js + minimal JS) |
| Performance | Slower, heavy JavaScript | Fast, lightweight, optimized |
| Compatibility with Hyvä | Requires fallback modules or custom fixes | Fully compatible |
| User Experience | Complex and slower checkout flow | Smooth, fast, and conversion-focused |
| Maintenance | Complex and harder to manage | Cleaner and easier to maintain |
| Recommendation | Not ideal for Hyvä-based stores | Strongly recommended for full optimization |
Top 5 Common Hyvä Theme Installation Errors and How to Fix Them
Error 1 :
- Error: Could not find package hyva-themes/magento2-default-theme
- Cause: Hyvä Composer repository is missing or credentials are incorrect
- Fix: Add the Hyvä repository, verify credentials, and run composer update
Re-run composer config repositories.hyva-themes composer https://packages.hyva.io/dist/ and verify your auth.json credentials match the token in your Hyvä portal.
Error 2 :
- Error: Invalid license key
- Cause: The license key is incorrect or assigned to a different domain
- Fix: Log in to hyva.io, verify the correct domain assignment, and copy the license key again from the portal
Error 3:
- Error: Blank page or CSS not loading after deployment
- Cause: Tailwind CSS not compiled or static content not deployed
- Fix: Run frontend build (npm install && npm run build), then deploy static content using
php bin/magento setup:static-content:deployand clear cache
bash
cd app/design/frontend/YourVendor/hyva-child/web/tailwind
npm run build-prod
php bin/magento setup:static-content:deploy en_US -f
php bin/magento cache:flush
Error 4:
- Error: Tailwind CSS classes not applying to custom content!
- Cause: Tailwind’s content purge configuration does not include your custom template files.
- Fix: Add your template paths to tailwind.config.js in the content array: and clear cache
content: [
'../../**/*.phtml',
'../../**/*.html',
// Add your custom paths here
]
Then rebuild: npm run build-prod
Magento 2 Hyvä Theme vs. Luma: Performance Comparison Guide for 2026
| Metric | Luma Theme | Hyvä Theme |
|---|---|---|
| Google Lighthouse (Mobile) | 15–40 | 85–100 |
| JavaScript Bundle Size | ~300–500KB | ~30–80KB |
| Time to Interactive | 8–15 seconds | 1–3 seconds |
| Core Web Vitals (LCP) | Often fails | Typically passes |
| CSS Framework | CSS/LESS | Tailwind CSS |
| Reactive UI Library | KnockoutJS | Alpine.js |
| Template Engine | PHTML + KO HTML | PHTML + Alpine |
| Developer Learning Curve | High | Medium |
If you want to explore a detailed comparison between the Hyvä theme and the Magento Luma theme, see the section below.
Frequently Asked Questions About Hyvä Theme Magento 2.
Yes. Hyvä 1.3.x is compatible with Magento 2.4.4 through 2.4.7. Always verify the compatibility matrix before upgrading either Magento or Hyvä.
Yes, Hyvä supports both Magento Open Source and Adobe Commerce. Some Adobe Commerce-specific features like Page Builder require additional Hyvä compatibility modules.
No. Hyvä and PWA Studio are separate approaches to Magento frontend development. Hyvä is server-side rendered with a progressive enhancement approach, while PWA Studio is a full headless/SPA architecture. They are not interchangeable.
Hyvä Theme covers all pages except checkout. Hyvä Checkout is a separate product that replaces the default Magento checkout with a Hyvä-native implementation. Both have separate licenses, though bundle pricing is sometimes available.
India has a growing ecosystem of skilled Hyvä theme developers, and a few agencies have distinguished themselves through certified expertise and proven project delivery. Among the top names is iCreative Technologies — a certified Hyvä Bronze Partner agency based in India and expert team of Hyva Theme Developers and Hyva Specialist.
