1. Getting Started with Hyvä Theme

Hyvä Theme 1.4.0 will be available for free as Open Source on 10. November 2025

Visit hyva.io for more information.

Requirements

Magento 2.4.4-p9, 2.4.5-p8, 2.4.6-p7, 2.4.7-p1 or higher
A Hyvä packagist.com key
PHP 7.4, 8.1, 8.2, 8.3 or 8.4

System Requirements

The system requirements depend on the versions of Magento and Tailwind CSS in use.

At the time of writing, a node version >= 20.0.0 is required on development instances to run the tailwind compiler. We recommend creating the bundle on development or staging instance, not on production.

The system requirements for Magento can be found in the devdocs.

We will drop support for PHP 7.4 at the end of 2025

CSP support in version 1.3.11 of Hyvä Theme Module

Hyvä release 1.3.11 introduced a requirement for the CSP Nonce Provider, which is only present since Magento version 2.4.4.
Therefore, older Magento 2 versions are no longer supported.
Users unable to update to one of the Magento versions listed above must use Hyvä versions prior to 1.3.11.

Getting Started

You need a valid Hyvä packagist.com key.

Get a free key by registering an account at hyva.io and creating one from your account dashboard.

You will receive instruction like the following after creating your packagist.com key:

# this command adds your key to your projects auth.json file
# replace yourLicenseAuthentificationKey with your own key
composer config --auth http-basic.hyva-themes.repo.packagist.com token yourLicenseAuthentificationKey
# replace yourProjectName with your project name
composer config repositories.private-packagist composer https://hyva-themes.repo.packagist.com/yourProjectName/

Run those commands, and then, install the theme and its dependencies with composer:

composer require hyva-themes/magento2-default-theme

Next, run the Magento installer:

bin/magento setup:upgrade

Navigate to the Content > Design > Configuration admin section and activate the hyva/default theme.

Ensure a theme is set on the Website

Setting hyva/default on a store view and keeping the lower Website and Store set to -- No Theme -- will cause issues on the storefront.
If you set the Hyvä theme at a Store or Store View level, be sure to also set a theme on the Website.
It does not matter what theme - it could be Luma of Hyvä or any other theme - as long as it is set.

In developer mode, you should now be able to see the theme in action on the frontend. A cache flush might be required.

In production deploy mode, running bin/magento setup:static-content:deploy is required.

In default deploy mode the newly installed modules will not be automatically enabled, so you have to do so using bin/magento module:enable for each one. That said, you should never operate a Magento store in default mode anyway.

Now you are ready to create your child theme. Continue reading with: Building your Theme.

Additional Steps

Disabling Magento Captcha

Captcha Support

Hyvä does not support the old Magento captcha implementation, which is enabled by default.

Instead, use one of the three Google ReCaptcha versions supported by Magento: ReCaptcha V3 invisible, V2 invisible and v2 "I'm not a robot".

Please disable the default Magento Captcha for forms to work:

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

Disabling the built-in minification and bundling

We generally recommend switching off the built-in minification and bundling of HTML, CSS and JS, as they don't benefit Hyvä sites, and even tend do harm, that is, produce overhead and maybe cause unwanted effects.

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

Be sure to keep the settings enabled for any store views that use Luma based themes. See the FAQ setup:static-content:deploy fails minifying CSS regarding CSS minification if you encounter issues.

Ensure required GraphQL modules are enabled

By default all Magento GraphQL modules are enabled.

However, often unused GraphQL modules are disabled in Magento stores using the Luma theme.

Hyvä uses of some of the Magento GraphQL API, so the following modules need to be enabled:

Module	composer package name
Magento_BundleGraphQl	magento/module-bundle-graph-ql
Magento_CatalogCustomerGraphQl	magento/module-catalog-customer-graph-ql
Magento_CatalogGraphQl	magento/module-catalog-graph-ql
Magento_CatalogRuleGraphQl	magento/module-catalog-rule-graph-ql
Magento_CatalogUrlRewriteGraphQl	magento/module-catalog-url-rewrite-graph-ql
Magento_ConfigurableProductGraphQl	magento/module-configurable-product-graph-ql
Magento_CustomerGraphQl	magento/module-customer-graph-ql
Magento_DirectoryGraphQl	magento/module-directory-graph-ql
Magento_DownloadableGraphQl	magento/module-downloadable-graph-ql
Magento_EavGraphQl	magento/module-eav-graph-ql
Magento_GraphQl	magento/module-graph-ql
Magento_GroupedProductGraphQl	magento/module-grouped-product-graph-ql
Magento_QuoteGraphQl	magento/module-quote-graph-ql
Magento_GraphQlCache	magento/module-graph-ql-cache
Magento_RelatedProductGraphQl	magento/module-related-product-graph-ql
Magento_ReviewGraphQl	magento/module-review-graph-ql
Magento_SalesGraphQl	magento/module-sales-graph-ql
Magento_StoreGraphQl	magento/module-store-graph-ql
Magento_SwatchesGraphQl	magento/module-swatches-graph-ql
Magento_UrlRewriteGraphQl	magento/module-url-rewrite-graph-ql
Magento_WishlistGraphQl	magento/module-wishlist-graph-ql

Are all GraphQL modules required?

Most of the time not all of these GraphQL modules are required. Which modules are required depends on what features are used. For example, if Recently Viewed Products are not enabled, then the Catalog GraphQL module is not required at all.

Checking which GraphQL modules are enabled

Run the following command and check that all modules are enabled:

bin/magento module:status Magento_BundleGraphQl Magento_CatalogCustomerGraphQl Magento_CatalogGraphQl Magento_CatalogRuleGraphQl Magento_CatalogUrlRewriteGraphQl Magento_ConfigurableProductGraphQl Magento_CustomerGraphQl Magento_DirectoryGraphQl Magento_DownloadableGraphQl Magento_EavGraphQl Magento_GraphQl Magento_GroupedProductGraphQl Magento_QuoteGraphQl Magento_GraphQlCache Magento_RelatedProductGraphQl Magento_ReviewGraphQl Magento_SalesGraphQl Magento_StoreGraphQl Magento_SwatchesGraphQl Magento_UrlRewriteGraphQl Magento_WishlistGraphQl

The expected output is something like this:

Magento_BundleGraphQl : Module is enabled
Magento_CatalogCustomerGraphQl : Module is enabled
Magento_CatalogGraphQl : Module is enabled
Magento_CatalogRuleGraphQl : Module is enabled
Magento_CatalogUrlRewriteGraphQl : Module is enabled
Magento_ConfigurableProductGraphQl : Module is enabled
Magento_CustomerGraphQl : Module is enabled
Magento_DirectoryGraphQl : Module is enabled
Magento_DownloadableGraphQl : Module is enabled
Magento_EavGraphQl : Module is enabled
Magento_GraphQl : Module is enabled
Magento_GroupedProductGraphQl : Module is enabled
Magento_QuoteGraphQl : Module is enabled
Magento_GraphQlCache : Module is enabled
Magento_RelatedProductGraphQl : Module is enabled
Magento_ReviewGraphQl : Module is enabled
Magento_SalesGraphQl : Module is enabled
Magento_StoreGraphQl : Module is enabled
Magento_SwatchesGraphQl : Module is enabled
Magento_UrlRewriteGraphQl : Module is enabled
Magento_WishlistGraphQl : Module is enabled

For Contributions and for Technology Partners

Getting Started

Technology and contributing partners have access to Hyvä repositories at gitlab.hyva.io

GitLab repositories can be configured in the root Magento composer.json as composer repositories. this allows checking out tags and branches, and pushing contributions to gitlab.hyva.io.

Tip

Ensure your SSH key is set in your Hyvä Gitlab account, as well as on github.com. If you use Docker, check that your SSH key is available in the container running Composer.

To configure and install Hyvä directly from GitLab with composer, run these commands:

# hosted on private gitlab:
composer config repositories.hyva-themes/magento2-theme-module git git@gitlab.hyva.io:hyva-themes/magento2-theme-module.git
composer config repositories.hyva-themes/magento2-base-layout-reset git git@gitlab.hyva.io:hyva-themes/magento2-base-layout-reset.git
composer config repositories.hyva-themes/magento2-email-module git git@gitlab.hyva.io:hyva-themes/magento2-email-module.git
composer config repositories.hyva-themes/magento2-default-theme git git@gitlab.hyva.io:hyva-themes/magento2-default-theme.git
composer config repositories.hyva-themes/magento2-order-cancellation-webapi git git@gitlab.hyva.io:hyva-themes/magento2-order-cancellation-webapi.git
composer config repositories.hyva-themes/magento2-compat-module-fallback git git@gitlab.hyva.io:hyva-themes/magento2-compat-module-fallback.git
composer config repositories.hyva-themes/magento2-mollie-theme-bundle git git@gitlab.hyva.io:hyva-themes/hyva-compat/magento2-mollie-theme-bundle.git

composer require hyva-themes/magento2-default-theme --prefer-source

Next, run bin/magento setup:upgrade from your project’s root.

Do not use ssh-key authentication in CI/CD!

We do not guarantee availability of GitLab. Always use packagist.com for build pipelines and for production.