Table of Contents & Menu
On this page
Navigation

How to Upgrade

Introduction

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

The default-theme

The default-theme provides templates, styles, and layout for your website's visual design.
When creating a custom theme, you'll customize copies of these files. Unmodified files load from the default-theme via Magento's theme fallback.

More customized files mean more work during an upgrade.

Typically, only customized templates with relevant DOM structure changes require updates.
A diff tool helps quickly scan file changes, allowing you to skip files with only class name modifications.

The theme-module

The theme-module supplies essential utilities and infrastructure for all Hyvä themes.
Its files are rarely customized in child themes.
Hyvä is committed to avoiding backward compatibility-breaking changes for this module.

It's always safe to update the theme-module to its latest version. Your theme will remain functional even if it hasn't been updated yet.

The reset-theme

For hyva-theme 1.3.17 or older only

Since release 1.3.18 the Hyvä Theme no longer uses a reset-theme parent.

hyva-theme 1.3.17 and Magento 2.4.8 compatibility

After updating to Magento 2.4.8, update hyva-themes/magento2-reset-theme to version 1.1.10 to fix Hyvä style application issues. Run:

composer require hyva-themes/magento2-reset-theme:1.1.10

If `root.phtml` is overwritten, add these two lines to include CSS in your HTML head output:

<?= /* @noEscape */ $headCritical ?? '' ?>
<?= /* @noEscape */ $headAssets ?? '' ?>

Full upgrade or theme-module only?

Always upgrade the theme-module. Our backward compatibility commitment means this should not introduce breaking changes, but always review upgrade notes.
Theme-module upgrades are typically smooth and fast.

Integrating all changes from a Hyvä default theme release into a child theme isn't always necessary. Partial upgrades are possible.
Depending on project requirements, an existing theme can often remain unchanged for extended periods.

Security

We will clearly announce security-related changes in upgrade notes and release announcements.
If needed, we'll provide a dedicated security patch, separate from other release changes.

Long Term Support

Periodically, ecosystem changes (e.g., new Tailwind CSS, Alpine.js, or backward-incompatible Magento versions) may necessitate child theme updates.
In such cases, Hyvä will maintain older theme and theme-module branches, providing security releases. Select new features may also be backported to support a wider Hyvä version range for extension vendors. The duration of security releases for older Hyvä versions is currently unspecified.

The Upgrade Process

  1. Review version-specific upgrade notes in the docs for backward-incompatible changes.
  2. Consult the changelog for new theme-module and default-theme versions (docs or GitLab).
  3. Upgrade the theme-module.
  4. Inspect changes in the new default-theme version for each customized theme file (see tooling below).
  5. Upgrade the default-theme.
  6. Apply necessary changes from step 4 to your customized theme.

Upgrade Tooling

Helpful tools for this process include:

You can also use git:
First, copy your customized theme to a temporary folder and run:
git init && git commit -m"Initial commit.
Then delete everything and copy in the updated default-theme.
Now, git diff will reveal all changes.

For a nicely formatted patch (credit: Peter Jaap Blaakmeer, Elgentos), use this command: 

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