Skip to content

Upgrading to 1.3.21

Release 1.3.21 introduces the generated base layout reset module, which improves TTFB performance on cold cache requests. The release also changes the licensing to AFL/OSL for the default theme and OSL for the theme-module, and includes a bugfix for the CSP version of the default theme.

Backward Incompatible Changes

While most updated lines in this release relate to the license change, there is one significant architectural change that may affect custom themes and third-party extensions.

Replacing hyva-themes/magento2-reset-theme with hyva-themes/magento2-base-layout-reset

The default theme now uses the hyva-themes/magento2-base-layout-reset module instead of the previous hyva-themes/magento2-reset-theme. This change is also included in Hyvä 1.4.0.

Why this change?

The previous reset-theme approach loaded layout XML files and then "undid" block declarations from module layouts. The new generated base layout reset module creates layout instructions without block declarations on the fly, providing two key benefits:

  1. Faster cold cache performance: Fewer layout XML files need to be loaded and processed, reducing TTFB on requests hitting a cold layout cache
  2. Automatic compatibility: New Magento core modules are automatically included in the reset without manual updates

Migration Options

The generated base layout reset is backward compatible—existing themes continue to work without changes. You have two options:

Option 1: Keep existing setup (no changes required)

Themes extending directly from the reset-theme will continue to function as long as hyva-themes/magento2-reset-theme remains installed. If the upgrade removes it (because it was only a transitive dependency of the default-theme), reinstall it explicitly:

composer require hyva-themes/magento2-reset-theme

Option 2: Migrate to generated base layout reset (recommended)

For improved performance, migrate your custom Hyvä base themes to use the generated base layout reset. See the generated base layout documentation for migration steps and tooling.

Third-Party Extension Compatibility

Theme detection method changed

Some third-party extensions detect Hyvä themes by iterating over parent themes and checking if any starts with Hyva/. This approach no longer works with the generated base layout reset.

Extensions should use the \Hyva\Theme\Service\HyvaThemes service class instead (available since Hyvä 1.3.18). See the extension compatibility documentation for implementation details that maintain compatibility with older Hyvä versions.

Changelogs

Changelogs are available from the CHANGELOG.md in the codebase, or here:

Tooling

Please refer to the Hyvä Theme upgrade docs for helpful information on how to upgrade.