How to Install Hyvä Theme in Magento 2: Complete Setup Guide

This guide installs the free, open-source Hyvä Theme on a Magento 2.4.x store, activates it, applies the settings Hyvä needs, and creates a child theme where your own design lives. Follow it on a development or staging environment first — never directly on production.

Requirements

• Magento Open Source or Adobe Commerce 2.4.4 or later at a recent patch level (2.4.8 or 2.4.9 recommended).
• A PHP version supported by both your Magento release and Hyvä (PHP 8.1–8.4 per Hyvä's documentation at the time of writing).
• Node.js 20 or newer on development machines for building Tailwind CSS.
• A free Hyvä account to create a Composer key.

Step 1: Get Your Free Composer Key

Log in to your account at hyva.io, open the dashboard and create a licence key. Even though the theme is free, packages are distributed through Hyvä's private Packagist repository, so Composer needs this key.

Step 2: Configure Composer

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

Replace the key and project name with the values from your dashboard. The auth details are written to auth.json; do not commit that file to a public repository.

Step 3: Install the Theme

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

Step 4: Activate Hyvä

In the admin, go to Content → Design → Configuration, edit the store view and select hyva/default. If you assign it at store view level, make sure the website level also has a theme assigned.

Step 5: Apply Required Settings

Hyvä does not use Magento's RequireJS-based captcha or JavaScript bundling. Hyvä's documentation recommends:

# Disable the default Magento captcha for Hyvä store views (use reCAPTCHA instead)
bin/magento config:set customer/captcha/enable 0

# Disable Magento's own JS/CSS minification, merging and bundling for Hyvä store views
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/css/merge_css_files 0
bin/magento config:set dev/css/minify_files 0

bin/magento cache:flush

Hyvä also relies on some GraphQL modules (for example for the mini-cart and customer section data). If you disabled GraphQL modules to slim down your installation, check bin/magento module:status and re-enable the ones Hyvä lists as required.

Step 6: Create a Child Theme

Never edit the vendor/hyva-themes files. Create a child theme for your design:

mkdir -p app/design/frontend/MageServices/hyva-child/web

<?php
declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::THEME,
    'frontend/MageServices/hyva-child',
    __DIR__
);

<?xml version="1.0"?>
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>MageServices Hyvä Child</title>
    <parent>Hyva/default</parent>
</theme>

Use Hyva/default-csp as the parent instead if you want the CSP-compatible variant for strict Content Security Policy.

Step 7: Copy and Configure the Tailwind Build

cp -r vendor/hyva-themes/magento2-default-theme/web/* app/design/frontend/MageServices/hyva-child/web/

Then tell the build to include the parent theme's templates, so classes used there are kept in the generated CSS:

{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme" }
        ]
    }
}

Step 8: Build the CSS

cd app/design/frontend/MageServices/hyva-child/web/tailwind
npm ci --ignore-scripts
npm run build      # production build, writes web/css/styles.css
npm run watch      # rebuild on change while developing

Register the new theme with bin/magento setup:upgrade, select MageServices/hyva-child in Content → Design → Configuration, and flush the cache.

Step 9: Production Deployment

• Build the CSS during your CI/CD pipeline or on staging, not on the production server.
• Run bin/magento setup:static-content:deploy for your locales in production mode.
• Check every third-party module on the storefront and install or build Hyvä compatibility modules where needed.

Troubleshooting

Frequently Asked Questions

Do I need to pay for Hyvä?

Not for the Hyvä Theme since version 1.4.0. You need a free account and Composer key. Hyvä Checkout and other add-ons are paid.

Can I install Hyvä on one store view only?

Yes. Themes are assigned per store view, so you can run Hyvä on one store view and Luma on others while you migrate.

Should I build CSS on the production server?

No. Build it in CI or on staging and deploy the generated styles.css with your code.