Hyvä Theme Setup Guide for Magento 2.4.8: Install to Deploy

Setting up Hyvä on a Magento 2.4.8 store is not hard, but the order of the steps matters and a few details trip people up on the first project: where the Tailwind build lives, why styles look broken after a deploy, and how to handle modules that still expect Luma. This guide walks through a clean setup on a development environment, from Composer to a working child theme with its own CSS build.

If you are still deciding whether Hyvä is the right move, read Hyvä vs Luma for developers first. This article assumes the decision is made.

What you need before you start

• Magento Open Source or Adobe Commerce 2.4.x. Check the Hyvä documentation for the exact versions supported by the Hyvä release you plan to install.
• PHP 8.3 or 8.4 for Magento 2.4.8.
• Node.js and npm on the machine that builds the CSS. This is your local environment and your CI or build server, not necessarily production.
• Access to the Hyvä packages. How you get access, and what it costs, has changed over time. Check hyva.io for the current licensing and installation terms before you budget the project.

Do the first install on a local copy. A Docker based setup such as Warden or DDEV makes it easy to reset if something goes wrong. See local Magento environments with Docker and Warden if you need one.

Installing the packages with Composer

The Hyvä docs give you the repository configuration that matches your access type. Once Composer can see the packages, the install itself is a normal Composer require of the default theme package. It pulls in the theme module and the other base packages as dependencies.

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

After setup:upgrade you will have new modules enabled (the Hyvä theme module and its dependencies) and a new theme registered as Hyva/default. Nothing changes on the storefront yet because the store view still points to Luma or your current theme.

Disable modules Hyvä does not need

Some Magento modules only add Luma frontend code. Hyvä does not use them and some of them are better disabled on a Hyvä store. The Hyvä documentation keeps the current list, so follow it rather than a list copied from an old blog post. Disable modules with bin/magento module:disable in development, commit the resulting app/etc/config.php, and let your deploy pick it up.

Create a child theme from day one

Never edit vendor/hyva-themes/magento2-default-theme and avoid using Hyva/default directly in production. A child theme lets you update Hyvä with Composer and keep your changes separate. The structure is the same as any Magento theme, which is covered in more depth in creating a Magento 2 child theme.

<?xml version="1.0"?>
<!-- app/design/frontend/Acme/hyva/theme.xml -->
<theme xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/theme.xsd">
    <title>Acme Hyva</title>
    <parent>Hyva/default</parent>
</theme>

<?php
// app/design/frontend/Acme/hyva/registration.php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(ComponentRegistrar::THEME, 'frontend/Acme/hyva', __DIR__);

Then copy the Tailwind build folder from the parent theme into your child theme. This is the part people miss. The CSS is not inherited at build time the way templates are. Your theme owns its own build and its own output file.

mkdir -p app/design/frontend/Acme/hyva/web
cp -r vendor/hyva-themes/magento2-default-theme/web/tailwind app/design/frontend/Acme/hyva/web/

Run setup:upgrade again so Magento registers the new theme, then assign it to the store view in the admin under Content, Design, Configuration. You can also do it from the CLI if your deploy scripts manage design config, but the admin is fine for a first setup.

The Tailwind build

Hyvä ships CSS as a compiled file. Tailwind scans your templates, layout XML and JavaScript for class names and generates only the CSS that is actually used. That means a class that exists only in the database (for example in a CMS block typed by a content editor) will not be in the output unless Tailwind can see it somewhere in the scanned paths, or you add it to a safelist.

Generate the module config

Modules that ship Hyvä templates can register their own Tailwind sources. The Hyvä theme module collects them into a JSON file so the build knows which module folders to scan.

bin/magento hyva:config:generate

This writes app/etc/hyva-themes.json. Run it again whenever you install or remove a module that has Hyvä specific frontend code. Many teams run it as part of the build step in CI so it never gets out of date.

Install and build

cd app/design/frontend/Acme/hyva/web/tailwind
npm ci
npm run build

The npm script names depend on the Hyvä version you installed. Older releases used build-prod and watch, newer ones may differ. Open package.json in the copied folder and use the scripts listed there. During development run the watch script in a separate terminal so CSS rebuilds when you save a template.

The output lands in web/css/styles.css inside your theme. Magento then treats it like any other static asset, which means static content deploy publishes it to pub/static.

Should you commit the compiled CSS?

There are two valid approaches:

1. Build in CI. Node runs in your pipeline, the compiled styles.css is produced before setup:static-content:deploy, and production servers never need Node. This is cleaner and what I recommend when there is a pipeline.
2. Commit the compiled file. Simpler for small teams without CI, but you must remember to rebuild and commit after every template change, and merge conflicts in a generated file are annoying.

Whatever you pick, the rule is the same: the CSS has to be built before static content deploy runs, or you publish stale styles. If you are setting up a pipeline, the approach in CI/CD for Magento with GitHub Actions works well with a Node step added before the deploy step.

Overriding templates and layout

Overrides work the same as in any Magento theme. To change a Hyvä template, copy it from the parent theme or module into the matching path in your child theme.

# override a template that lives in the parent theme
mkdir -p app/design/frontend/Acme/hyva/Magento_Catalog/templates/product/list
cp vendor/hyva-themes/magento2-default-theme/Magento_Catalog/templates/product/list/item.phtml \
   app/design/frontend/Acme/hyva/Magento_Catalog/templates/product/list/item.phtml

Copy only what you change. Every copied template is a file you need to compare against the parent on each Hyvä upgrade. A child theme with a hundred overridden templates will make upgrades slow.

Layout XML also works as usual. One thing specific to Hyvä is that the theme module adds extra layout handles prefixed with hyva_ when a Hyvä theme is active, for example hyva_catalog_product_view. Modules use these handles to apply Hyvä specific layout changes that should not affect a Luma store running the same code base.

Modules that are not Hyvä compatible yet

Any extension that adds frontend JavaScript built on RequireJS, jQuery or Knockout will not work on a Hyvä page as it is. The backend parts are fine. You have three options for each one: a compatibility module, your own Hyvä templates for that module, or a Luma fallback for the routes that need it. This deserves its own planning, covered in Hyvä compatibility modules.

During setup, make a list of every enabled third party module with frontend output. Check each one for a Hyvä compatible version from the vendor before you write anything yourself.

Production deploy checklist

• Run hyva:config:generate and the Tailwind build before static content deploy.
• Deploy static content for the child theme and the locales you use. Restricting the deploy to the themes you really serve keeps it fast.
• Flush full page cache after the first switch. Old pages from Luma will otherwise keep being served from Varnish or the built in cache.
• Check the mini cart, customer login state and messages on a cached page. These come from customer data sections, which Hyvä reads differently from Luma.
• Run Lighthouse or PageSpeed on a category page and a product page with real data, not on an empty demo catalog.

bin/magento hyva:config:generate
npm --prefix app/design/frontend/Acme/hyva/web/tailwind ci
npm --prefix app/design/frontend/Acme/hyva/web/tailwind run build
bin/magento setup:static-content:deploy -f --theme Acme/hyva en_US
bin/magento cache:flush

Common setup problems

The page renders without styles

Usually the child theme has no compiled styles.css, or static content was deployed before the build ran. Check that web/css/styles.css exists in your theme and that the file in pub/static is recent.

A class works locally but not in production

The class is used somewhere Tailwind does not scan, often a CMS block or a module that was not included in hyva-themes.json. Add the path to the content sources or safelist the class.

Some pages still load RequireJS

That route is using a Luma fallback, or a module is adding scripts through layout XML. Check the page source and the fallback configuration.

FAQ

Do I need Node.js on the production server for Hyvä?

No, as long as the Tailwind CSS is built before deploy, either in CI or on a build machine. Production only needs the compiled styles.css that static content deploy publishes.

Can I use Hyva/default directly without a child theme?

It works, but any change would mean editing vendor files. A child theme from the start keeps your changes safe across Hyvä upgrades.

What does bin/magento hyva:config:generate do?

It writes app/etc/hyva-themes.json with the paths of modules that register Hyvä frontend sources, so the Tailwind build scans their templates for class names.

How much does a Hyvä license cost?

Licensing and pricing have changed over time, so check hyva.io for the current terms rather than relying on older articles.

I am available for freelance Magento and Hyvä work. If you need help setting up or migrating a store, get in touch.