Table of Contents & Menu
On this page
Navigation

Upgrading to 1.3.21

Hyvä 1.3.21 introduces the generated base layout reset module, improving TTFB performance on cold cache requests. This release also updates 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 updates in this release relate to license changes, one significant architectural change 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, replacing the previous hyva-themes/magento2-reset-theme. This change is also part of Hyvä 1.4.0.

Why this change?

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

  1. Faster cold cache performance: Reduces TTFB on cold layout cache requests by loading and processing fewer layout XML files.
  2. Automatic compatibility: Automatically includes new Magento core modules in the reset without manual updates.

Migration Options

The new generated base layout reset is backward compatible, meaning existing themes will 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 (e.g., if it was a transitive dependency), 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. Refer to 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

View changelogs in the codebase (CHANGELOG.md) or via these links:

Tooling

Refer to the Hyvä Theme upgrade docs for upgrade documentation.