Skip to content

How to Upgrade


Hyvä has two main components, the hyva-themes/magento2-default-theme and the hyva-themes/magento2-theme-module.

The default-theme

The default-theme contains the templates, styles and layout instructions that define the visual representation of a website.
When creating a custom theme, customized copies of files within the default-theme will need to be created. Files that are not customized are loaded from the default-theme through the Magento theme fallback.

The more files are customized, the more work an upgrade becomes.

Usually you only have to update customized templates that have DOM structure changes that are relevant or are breaking some new feature.
A diff will allow you to quickly scan the changes made to a file and move on to the next if only classname changes where made.

The theme-module

The theme-module provides utilities and required infrastructure code that is used by all Hyvä based themes.
The files within the theme-module are rarely customized when creating a custom theme.
We (Hyvä) tries very hard to avoid backward compatibility breaking changes for the theme-module.

This means it is always safe to update the theme-module to the latest version. Even if a theme itself isn't updated (yet), it will continue to work with a newer version of the theme-module.

The Upgrade Process

  1. Check version specific upgrade notes here in the docs. If there are any backward incompatible changes they will be listed there.
  2. Check the changelog for the new version for both the theme-module and the default-theme here in the docs or in GitLab.
  3. Upgrade the theme-module.
  4. For every customized theme file, inspect the changes made in the default-theme for the new version. See below for helpful tooling.
  5. Upgrade the default-theme.
  6. Apply the required changes from step 4. to your customized theme.

Upgrade Tooling

Good tooling can help with this step, for example the

Good old git can be used, too:
First, copy the changed theme to some temporary folder and run
git init && git commit -m"Initial commit.
Then delete everything and copy in the updated version of the default-theme.
Now a git diff will reveal all changes.

Try this command to see a nicely formatted patch (thanks to Peter Jaap Blaakmeer from Elgentos):

git format-patch -1 HEAD --no-notes --no-cover-letter --no-stat --no-prefix --no-signature