Overview

The first step is to create your Hyvä theme that will contain all your customizations.

Create your own Theme

There are two approaches to creating your theme:

1. You can create a child theme, the same way default Magento works
2. You can create a duplicate theme of the hyva-themes/magento2-default-theme and modify that

How do I choose between a child theme or a duplicate?

We recommend you start with the child-theme approach. This is simpler to create and also more upgradable.

If you are very familiar with Hyvä and Magento development and want to heavily customize and optimize your Hyvä Theme, you might want to go for the duplicate theme approach.

Start with a child theme

We recommend you always start with a child theme.
It is less work to create and makes merging changes during upgrades simpler.
If you are satisfied with the result and want to go even further, you can still convert it to a duplicated base theme later. To do so you can copy all missing files from the default theme into your child theme and then change the parent theme to Hyva/reset.

Creating a Child Theme

Follow the instructions from The official Magento Docs to create a new theme.

Set the parent theme to Hyva/default.

Theme Preview Image

Please note we ship with a preview.png file instead of preview.jpg, which is referenced in the theme’s theme.xml.

Child themes in app/design/

Copy the web directory

Copy the web directory with all files from the parent theme vendor/hyva-themes/magento2-default-theme/web/ to your own child theme app/design/frontend/Acme/default/web/.

Tailwind config parent theme path

Next, you must configure the parent theme path in the web/tailwind/tailwind.config.js file of your child theme.

For example, if your child theme tailwind.config.js file is app/design/frontend/Acme/default/web/tailwind/tailwind.config.js, then configure the parent theme by enabling the line after the comment // parent theme in Vendor:

Hyvä 1.2.x and Tailwind v3

The following code snippet is for Tailwind v3, which has been used in Hyvä themes since release 1.2.0.

module.exports = {
  ...
  // keep the original settings from tailwind.config.js
  // only add the path below to the purge > content settings
  ...
  content: [
    // this theme's phtml and layout XML files
    '../../**/*.phtml',
    '../../*/layout/*.xml',
    '../../*/page_layout/override/base/*.xml',
    // parent theme in Vendor (if this is a child-theme)
    //'../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
    //'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/layout/*.xml',
    //'../../../../../../../vendor/hyva-themes/magento2-default-theme/*/page_layout/override/base/*.xml',
    // app/code phtml files (if need tailwind classes from app/code modules)
    //'../../../../../../../app/code/**/*.phtml',
  ]
}
...

Hyvä 1.1.x and Tailwind v2

Older Hyvä versions 1.1.x use Tailwind v2. In the configuration for that version, the path to the content section is slightly different.
If your theme is based on an older 1.1.x version of Hyvä and you haven't upgraded it to Tailwind v3, you need to use that structure, where content is nested inside a purge parent object:

  module.exports = {
  ...
  // keep the original settings from tailwind.config.js
  // only add the path below to the purge > content settings
  ...
  purge: {
    content: [
      // this theme's phtml and layout XML files
      '../../**/*.phtml',
      '../../*/layout/*.xml',
      // parent theme in Vendor
      '../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml',
      ...
    ]
  }
}
...

Extending your theme works just like with default Magento Themes. You can override .phtml files and extend layout xml the same way as you could with a default Magento theme based on Luma.

Child themes in vendor/

If you are working in a child theme in vendor/ instead of app/design/ (which is an unusual scenario, but it may happen), be sure to adjust the content paths to the parent default-theme theme accordingly:

    // parent theme in Vendor (if this is a child-theme in vendor)
    '../../../hyva-themes/magento2-default-theme/*/page_layout/override/base/*.xml',
    '../../../hyva-themes/magento2-default-theme/*/layout/*.xml',
    '../../../hyva-themes/magento2-default-theme/**/*.phtml',
  ]

Generating your themes styles.css

Once you make a change to your theme, be aware that you have to regenerate your theme's styles.css file.
For more information please read all instructions on working with Tailwind CSS, generating the styles.css file, and Tailwind CSS content configuration.

Creating a Duplicated Theme

Why would you want to create a Theme duplicate instead of a Child Theme?

The reason you might not want to inherit from the Hyva/default theme is that you will likely end up with a lot of unused tailwind classes. The CSS classes used in the parent theme, that are overwritten in the child theme will still be generated in the final Tailwind CSS file, because of the way the parent theme templates are scanned in addition to the child theme works.

You will need to be comfortable with advanced purging methods to inherit from the Hyva/default theme and at the same time avoid adding any unused tailwind classes if you want to work with child themes instead.

Creating a Hyvä Base Theme

You can create your own base theme either in app/design/frontend or in a vendor package.

To do this, copy the Hyva/default theme into your desired location. In this example, we’ll assume you’re using app/design/frontend/Acme/default.

Edit the registration.php, theme.xml, and composer.json files to reflect your theme name.

app/design/frontend/Acme/
├── default/
│   ├── registration.php
│   ├── theme.xml
│   ├── composer.json

Editing layout in your Hyvä Base Theme

All layout in your theme lives in the base theme you created. The Hyva/reset theme creates an empty layout with containers only. No blocks are declared in the reset theme.

That means, if you remove a layout xml file from your theme, the blocks are entirely gone from the front end.

Removing blocks is still an option for child themes, but not declaring them in the first place is a perfect solution to create the smallest amount of code you need to build your template.

Info

In case you were wondering, <referenceBlock name="block.name" remove="true"/> works, but you may also delete the original <block name="block-name"> from layout.
If you were not wondering, don't worry.

Generating your themes styles.css

Once you make a change to a copy of the Hyvä default theme, be aware that you have to regenerate your theme's styles.css file.
For more information please read all instructions on working with Tailwind CSS, generating the styles.css file, and Tailwind CSS content configuration.