Getting Started with Hyvä Theme
Requirements
- Magento
2.4.4-p9,2.4.5-p8,2.4.6-p7,2.4.7-p1or higher - A Hyvä packagist.com key
- PHP
7.4,8.1,8.2,8.3or8.4
System Requirements
System requirements vary based on Magento and Tailwind CSS versions.
Node.js >= 20.0.0 is required on development instances for the Tailwind compiler. We recommend bundling on development or staging, not production.
Magento's system requirements are available 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ä 1.3.11+ requires Magento 2.4.4+ due to the CSP Nonce Provider. For older Magento 2 versions, use Hyvä versions prior to 1.3.11.
Installation
A valid Hyvä packagist.com key is required. Register at hyva.io and create a key from your account dashboard.
After creating your key, follow these instructions:
# 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/
After configuring your key, install the theme and its dependencies:
Then, run the Magento installer:
Activate the hyva/default theme in Content > Design > Configuration.
Ensure a theme is set on the Website
To prevent storefront issues, ensure a theme is set at the Website level if hyva/default is applied at the Store or Store View level. Any theme (Luma, Hyvä, etc.) will suffice.
In developer mode, the theme should now be visible on the frontend. A cache flush may be needed.
For production mode, run bin/magento setup:static-content:deploy.
In default mode, manually enable new modules with bin/magento module:enable. However, `default` mode is not recommended for Magento stores.
You are now ready to create your child theme. Continue with: Building your Theme.
Additional Steps
Disabling Magento Captcha
Captcha Support
Hyvä does not support the default Magento Captcha. Use one of Magento's supported Google ReCaptcha versions: V3 invisible, V2 invisible, or V2 "I'm not a robot".
Disable the default Magento Captcha for forms to function correctly:
Disabling the built-in minification and bundling
We recommend disabling Magento's built-in HTML, CSS, and JS minification and bundling. These features offer no benefit to Hyvä sites and can cause overhead or 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
Keep these settings enabled for Luma-based themes. Refer to the FAQ setup:static-content:deploy fails minifying CSS if you encounter issues.
Ensure required GraphQL modules are enabled
All Magento GraphQL modules are enabled by default.
However, Luma-based Magento stores often disable unused GraphQL modules.
Hyvä utilizes certain Magento GraphQL APIs, requiring the following modules 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?
Not all GraphQL modules are always required. The specific modules needed depend on the features in use (e.g., Catalog GraphQL is not needed if Recently Viewed Products are disabled).
Checking which GraphQL modules are enabled
To check if all modules are enabled, run:
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
Expected output:
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 can access Hyvä repositories at gitlab.hyva.io.
Configure GitLab repositories in your root Magento `composer.json` to check out tags/branches and push contributions to gitlab.hyva.io.
Tip
Ensure your SSH key is configured in your Hyvä GitLab and GitHub accounts. If using Docker, verify your SSH key is available in the Composer container.
To configure and install Hyvä directly from GitLab via Composer, run:
# hosted on private gitlab:
composer config repositories.hyva-themes/magento2-theme-module git [email protected]:hyva-themes/magento2-theme-module.git
composer config repositories.hyva-themes/magento2-base-layout-reset git [email protected]:hyva-themes/magento2-base-layout-reset.git
composer config repositories.hyva-themes/magento2-email-module git [email protected]:hyva-themes/magento2-email-module.git
composer config repositories.hyva-themes/magento2-default-theme git [email protected]:hyva-themes/magento2-default-theme.git
composer config repositories.hyva-themes/magento2-order-cancellation-webapi git [email protected]:hyva-themes/magento2-order-cancellation-webapi.git
composer config repositories.hyva-themes/magento2-compat-module-fallback git [email protected]:hyva-themes/magento2-compat-module-fallback.git
composer config repositories.hyva-themes/magento2-mollie-theme-bundle git [email protected]:hyva-themes/hyva-compat/magento2-mollie-theme-bundle.git
composer require hyva-themes/magento2-default-theme --prefer-source
Then, run `bin/magento setup:upgrade` from your project 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.
Activate the hyva/default theme in Content > Design > Configuration.
Ensure a theme is set on the Website
To prevent storefront issues, ensure a theme is set at the Website level if hyva/default is applied at the Store or Store View level. Any theme (Luma, Hyvä, etc.) will suffice.
In developer mode, the theme should now be visible on the frontend. A cache flush may be needed.
For production mode, run bin/magento setup:static-content:deploy.
In default mode, manually enable new modules with bin/magento module:enable. However, `default` mode is not recommended for Magento stores.
Additional Steps
Also, follow the Additional Steps outlined above.