Understanding the Hyvä Tailwind build process for custom modules

In the Hyvä theme, the hyva-sources command compiles the Tailwind CSS styles for the theme. The hyva-sources command uses the app/etc/hyva-themes.json file to identify the list of modules whose content should be included during compilation.

If we look at the gatherConfigData method in the HyvaModulesConfig class, it is responsible for gathering the data and writing the app/etc/hyva-themes.json configuration file.

    /**
     * Gather the data for and write the app/etc/hyva-themes.json config file
     *
     * The config structure is an array of all modules that want to hook into the tailwind styles build process.
     *
     * [
     *   "extensions": [
     *     ["src" => "vendor/vendor-name/magento2-module-name/src"],
     *     ...
     *   ]
     * ]
     *
     * Modules can add themselves to the list using the event "hyva_config_generate_before".
     * Any module registered with the \Hyva\CompatModuleFallback\Model\CompatModuleRegistry is added automatically.
     *
     * Note: more records besides "src" might be added in the future.
     *
     * @see \Hyva\CompatModuleFallback\Observer\HyvaThemeHyvaConfigGenerateBefore::execute()
     */
    public function gatherConfigData(): array
    {
        // Keep reference to current ObjectManager instance, so it can be reset later
        $currentObjectManager = ObjectManager::getInstance();

        $newObjectManager = $this->createObjectManagerWithCurrentModulesList();
        $eventManager     = $newObjectManager->create(EventManagerInterface::class);
        $configContainer  = new DataObject();
        $eventManager->dispatch('hyva_config_generate_before', ['config' => $configContainer]);

        // Revert ObjectManager to reset app state
        ObjectManager::setInstance($currentObjectManager);

        // Merge records with the same src (could happen for compat modules that also add an observer)
        $data = $configContainer->getData();
        $data['extensions'] = values(reduce($data['extensions'] ?? [], function (array $acc, array $record) {
            if ($path = $record['src'] ?? false) {
                $acc[$path] = merge($acc[$path] ?? [], $record);
            }
            return $acc;
        }, []));
        return $data;
    }vendor/hyva-themes/magento2-theme-module/src/Model/HyvaModulesConfig.php

There are two types of modules in the Hyvä theme:

1. Compatibility modules: These modules override the templates of the original Magento 2 modules to make them compatible with the Hyvä theme.
2. Custom modules: These are modules that you create to add new features or extends functionality within your Hyvä theme. They can include their own CSS styles that need to be added to the Tailwind build process.

Compatibility modules

If you create a compatibility module by registering it in the \Hyva\CompatModuleFallback\Model\CompatModuleRegistry, it is automatically added to the hyva-themes.json file. This is the automatic way to include a module in the Tailwind build process.

Custom modules

If you create a custom module specifically for the Hyvä theme and want to include its CSS styles in the Tailwind build process, you need to create an observer for the hyva_config_generate_before event and add the module path to the configuration.

Let’s assume we have a custom module named MyCompany_HyvaStyle.

1. Register the observer

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="hyva_config_generate_before">
        <observer name="mycompany_hyvastyle_config_generate_before" instance="MyCompany\HyvaStyle\Observer\RegisterModuleForHyvaConfig" />
    </event>
</config>MyCompany_HyvaStyle::etc/frontend/events.xml

2. Create the observer class to add the module path in the config

<?php
declare(strict_types=1);

namespace MyCompany\HyvaStyle\Observer;

use Magento\Framework\Component\ComponentRegistrar;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

class RegisterModuleForHyvaConfig implements ObserverInterface
{
    /**
     * @var ComponentRegistrar
     */
    private $componentRegistrar;

    public function __construct(ComponentRegistrar $componentRegistrar)
    {
        $this->componentRegistrar = $componentRegistrar;
    }

    public function execute(Observer $event)
    {
        $config = $event->getData('config');
        $extensions = $config->hasData('extensions') ? $config->getData('extensions') : [];

        $path = $this->componentRegistrar->getPath(ComponentRegistrar::MODULE, 'MyCompany_HyvaStyle');

        $extensions[] = ['src' => substr($path, strlen(BP) + 1)];

        $config->setData('extensions', $extensions);
    }
}MyCompany_HyvaStyle::Observer\RegisterModuleForHyvaConfig.php

After running the bin/magento hyva:config:generate command, the MyCompany_HyvaStyle module will be added to the hyva-themes.json file.

{
    "extensions": [
        {
            "src": "vendor/hyva-themes/magento2-theme-module/src"
        },
        {
            "src": "vendor/mollie/magento2-hyva-compatibility/src/Mollie_HyvaCompatibility"
        },
        { 
            "src": "app/code/MyCompany/HyvaStyle"
        }
    ]
}app/etc/hyva-themes.json

When you run the npm run generate command, the MyCompany_HyvaStyle module will be added to the hyva-source.css file, and the Tailwind classes used in *.phtml and *.xml files will be included in the generated styles.css file.

/**
 * This file is automatically generated.
 * Do not edit this file!
 *
 * To prevent modules from being added,
 * please exclude them in your theme using the hyva.config.json configuration.
 */

@source "../../../../../../../../vendor/hyva-themes/magento2-theme-module/src/**/*.phtml";
@source "../../../../../../../../vendor/hyva-themes/magento2-theme-module/src/**/*.xml";
@source "../../../../../../../../vendor/mollie/magento2-hyva-compatibility/src/Mollie_HyvaCompatibility/**/*.phtml";
@source "../../../../../../../../vendor/mollie/magento2-hyva-compatibility/src/Mollie_HyvaCompatibility/**/*.xml";
@source "../../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.phtml";
@source "../../../../../../../../vendor/hyva-themes/magento2-default-theme/**/*.xml";
@source "../../../../../../../code/Magediary/TestimonialSlider/**/*.phtml"; 
@source "../../../../../../../code/Magediary/TestimonialSlider/**/*.xml";Hyvä-child-theme::web/tailwind/generated/hyva-source.css

I hope this helps you understand how custom module CSS hooks into the Tailwind styles build process in the Hyvä theme. By following these steps, you can easily include your custom module’s CSS in the Tailwind build process and ensure it appears in the final compiled CSS output.

In the next blog, we will explore additional ways to hook custom module CSS into the Tailwind styles build process. Cheers!