Generated Base Layout Resets

Rationale

Prior to Hyvä 1.4.0, the default theme used a parent "reset-theme" to override and remove block layout declarations from module folders.

Starting with Hyvä 1.4.0, themes now use the hyva-themes/magento2-base-layout-reset module. This module dynamically generates base layout declarations in var/hyva-layout-resets/.

This new approach offers two key benefits:

• Improved Performance: Faster page requests when the layout cache is cold.
• Easier Maintainability: No need to update the reset theme when new Magento core modules are released.

Generating the base layout resets

Base layout resets are generated automatically as needed. You can also manually trigger their generation using the following command:

bin/magento hyva:base-layout-resets:generate

Installation

The magento2-base-layout-reset module is automatically installed as a Composer dependency when you install or upgrade hyva-themes/magento2-default-theme (or -csp) to version 1.4.0 or higher.

To explicitly install it, for example, when upgrading a custom Hyvä base theme, run:

composer require hyva-themes/magento2-base-layout-reset
bin/magento module:enable Hyva_BaseLayoutReset
bin/magento setup:upgrade

If your custom theme inherits from Hyva/default or Hyva/default-csp, no further steps are required after installation.

Configuring the generation folder

You can specify a custom path for the generated layout files in app/etc/env.php using the hyva_layout_resets_generation_directory key. Remember to use an absolute file path (starting with /).

Example:

return [
    'hyva_layout_resets_generation_directory' => '/var/www/html/generated/code/hyva-layout-resets/',
    ...

What determines if a theme is a Hyvä Theme

Previously, a theme was considered Hyvä-based if its inheritance chain included a theme named Hyva/ (e.g., Hyva/reset). With the new generated base layouts, themes no longer inherit from Hyva/reset, making this detection method obsolete.

To ensure proper detection, Hyvä base themes must now be explicitly registered. This is done by adding them to the $hyvaBaseThemes constructor argument of Hyva\Theme\Service\HyvaThemes via di.xml.

The Hyvä default themes are already configured within the hyva-themes/magento2-base-layout-reset module. If you have a custom Hyvä base theme that previously extended Hyva/reset and you are migrating it to use generated base layouts, you must add your theme to this array. It's recommended to do this in a di.xml file within a custom module.

<type name="Hyva\Theme\Service\HyvaThemes">
    <arguments>
        <argument name="hyvaBaseThemes" xsi:type="array">
            <item name="Hyva/reset" xsi:type="boolean">true</item>
            <item name="Hyva/default" xsi:type="boolean">true</item>
            <item name="Hyva/default-csp" xsi:type="boolean">true</item>
        </argument>
    </arguments>
</type>

Migrating custom Hyvä base themes

If you have a custom Hyvä base theme that directly extends Hyva/reset, you can migrate it to use the generated base layout reset.

NOTE: This migration is optional. Existing themes can continue using the reset theme without issues.

Migration Steps:

1. Add <update handle="default_hyva"/> to your theme's Magento_Theme/layout/default.xml.
2. Copy Magento_Theme/templates/root.phtml from the Hyva/reset theme into your Hyvä theme.
3. Remove <parent>Hyva/reset</parent> from your theme's theme.xml.
4. Update the theme table in the database, setting the parent_id of your theme to NULL.
5. Add your theme code to the hyvaBaseThemes array in the constructor argument for Hyva\Theme\Service\HyvaThemes within a di.xml file (preferably in a custom module).
6. Clear the cache.

The hyva-themes/magento2-base-layout-reset module provides commands to assist with these steps.

List Hyvä Theme reset information

To view all Hyvä themes and their migration status, run:

bin/magento hyva:base-layout-resets:info

Base Layout Reset migration command

To automatically migrate a Hyvä base theme to use the generated layout reset, run:

bin/magento hyva:base-layout-resets:migrate Vendor/theme

Replace Vendor/theme with your actual theme code.

NOTE: This command will modify app/etc/di.xml to add your theme to the hyvaBaseThemes argument. It is strongly recommended to move this declaration into a di.xml file within your custom module, as app/etc/di.xml is often not version-controlled and changes may be lost.

Third Party Extension Compatibility

Some third-party extensions might check if a theme is a Hyvä theme by iterating through its parent themes and looking for one starting with Hyva/ (like Hyva/reset). This method no longer works with generated base layouts, as Hyvä base themes now have no parent theme.

The correct way to determine if a theme is a Hyvä theme is to use the \Hyva\Theme\Service\HyvaThemes class. This class is available since hyva-themes/magento2-theme-module release 1.4.0.

To ensure this class is available, add a Composer dependency to your extension: "hyva-themes/magento2-theme-module": ">=1.4.0".

For compatibility with older Hyvä versions or non-Hyvä installations, you can check if the class exists and then use it. If it doesn't exist, fall back to the traditional parent theme hierarchy check:

if (class_exists(HyvaThemes::class)) {
    $service = ObjectManager::getInstance()->get(HyvaThemes::class);
    return $service->isHyvaTheme($theme)
} else {
    // existing code checking the parent themes
}

If you have a theme instance (ThemeInterface $theme), use the method:

isHyvaTheme(ThemeInterface $theme)

If you only have a string theme code, use the method:

isHyvaThemeCode(string $themeCode)

Both methods are available on the HyvaThemes class.