Module tailwind.config.js merging

Often compatibility modules need to add their templates and layout XML files to a themes tailwind.config.js content purge configuration.
Other tailwind.config.js configuration could need to be added to support a module, too. This feature is provided by a npm module @hyva-themes/hyva-modules.

This npm module is included with the Hyvä default theme since release 1.1.14, but it can also be added to themes based on older releases.

Module tailwind.config.js merging for 1.1.13 and older themes

First, run the following command to install the npm module to the theme within the theme web/tailwind directory.
```
npm install @hyva-themes/hyva-modules
```

Import the module in the themes tailwind.config.js file.

const hyvaModules = require('@hyva-themes/hyva-modules');

Wrap the value assigned to module.exports in a function call to hyvaModules.mergeTailwindConfig.

module.exports = hyvaModules.mergeTailwindConfig({
    // theme tailwind config here ...
})

Updating @hyva-themes/hyva-modules

In case an update of @hyva-themes/hyva-modules is released, and you want to pull that into your theme, run the following command to fetch the new version, replacing the 1.0.4 in the example with the desired version:

npm install @hyva-themes/hyva-modules@1.0.4

The npm module also contains functionality to merge postcss configuration from modules.

Adding a module to the tailwind purge config

1. Create the `tailwind.config.js` file

For modules the tailwind configuration is located at view/frontend/tailwind/tailwind.config.js.

Any paths are specified relative to this file. For example, to include the modules *.phtml templates into the tailwind config, use:

module.exports = {
  purge: {
    content: [
      '../templates/**/*.phtml',
    ]
  }
}

Note that any type of file can be added to the content path: layout XML, *.html, *.jsx files - whatever is needed. Adjust the content path in the modules tailwind.config.js according to your needs.

Skeleton compat modules contain this configuration out of the box since the release of 1.1.14

Other configuration can be added to the file, too, and will be merged into a themes tailwind configuration when the styles.css file is built.

Tailwind CSS v2 or v3?

Do I use the Tailwind CSS v2 or v3 purge content structure?

The script is smart enough to map a modules' purge config structure to the same one that is used in the theme.
If you don't have any preference, then we suggest you use the v3 structure.

Using `require()` inside a module

When using require with a node library inside a modules' view/frontend/tailwind/tailwind.config.js file, prefix the node module name the global variable themeDirRequire:

const colors = require(`${themeDirRequire}/tailwindcss/colors`);

The global variable themeDirRequire maps to the node_modules/ folder in the theme that is currently being built.

If you need to require node modules bundled with the module inside the frontend/tailwind directory, use the usual import syntax.

2. Add the module to the `app/etc/hyva-themes.json` file

A modules tailwind.config.js file will not be included in the build process immediately.
First, the module needs to be added to the Magento app/etc/hyva-themes.json file. This file contains a list of all installed modules that should be scanned for tailwind configuration or tailwind CSS.

Since Hyvä 1.1.15, the hyva-themes.json file is generated implicitly whenever a new module is status is changed by

bin/magento setup:upgrade
bin/magento module:enable
bin/magento module:disable

The file can also be explicitly generated by the command

bin/magento hyva:config:generate

With Hyvä version 1.1.14 on Magento 2.4.7 or newer this command needs to be run after a compat module is installed

Since Hyvä 1.1.15 this usually happens automatically through one of the commands listed above.

Before automatic tailwind.config.js merging was introduced, the purge content configuration in a theme would need to be adjusted to include the new theme.

Now no manual configuration changes are required.

The `app/etc/hyva-themes.json` file

When one of the following commands is run, Hyvä modules register themselves to be added to the file

bin/magento hyva:config:generate
bin/magento setup:upgrade
bin/magento module:enable
bin/magento module:disable

Any compatibility module that is registered with the Hyva\CompatModuleFallback\Model\CompatModuleRegistry (using etc/frontend/di.xml) is added to the file automatically.

Other modules besides compat modules can also register themselves to be included in the hyva-themes.json file using an event observer, as described below.

Registering a module for inclusion in `hyva-themes.json`

The app/etc/hyva-themes.json file contains a list of all installed modules that should be scanned for tailwind configuration or tailwind CSS.

This is not required for compat modules

Compatibility modules that use automatic template overrides (via the CompatModuleRegistry) are registered automatically.
This documentation might be useful for other modules.

Example for a generated hyva-themes.json file:

{
    "extensions": [
        {
            "src": "app\/code\/My\/Module"
        },
        {
            "src": "vendor\/hyva-themes\/magento2-magenerds-baseprice\/src"
        }
    ]
}

A module that needs to be included in the hyva-themes.json file, can do so by declaring an event observer in etc/frontend/events.xml for the event hyva_config_generate_before.

<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="MyModule" instance="Hyva\ExampleModule\Observer\RegisterModuleForHyvaConfig"/>
    </event>
</config>

The observer method will receive a configuration object which represents the data structure written to the JSON file.

To register itself for the tailwind theme configuration merge process, it needs to add the module path relative to the Magento root directory to the extensions[].src path in the file.

<?php

declare(strict_types=1);

namespace Hyva\ExampleModule\Observer;

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

class RegisterModuleForHyvaConfig implements ObserverInterface
{
    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') : [];

        $moduleName = implode('_', array_slice(explode('\\', __CLASS__), 0, 2));

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

        // Only use the path relative to the Magento base dir
        $extensions[] = ['src' => substr($path, strlen(BP) + 1)];

        $config->setData('extensions', $extensions);
    }
}

Removing Modules from `hyva-themes.json`

Sometimes you may wish to omit a compatibility module from this file - to exclude their custom styles, for example. There are a couple of ways to achieve this, depending on how the compatibility module has registered itself for inclusion in the hyva-themes.json file.

Compatibility Module Registry

For compatibility modules that have registered themselves with the compatibility module registry, they can be removed from the hyva-themes.json file by passing the module name to the Hyva\CompatModuleFallback\Observer\HyvaThemeHyvaConfigGenerateBefore class's exclusions array in di.xml.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <type name="Hyva\CompatModuleFallback\Observer\HyvaThemeHyvaConfigGenerateBefore">
        <arguments>
            <argument name="exclusions" xsi:type="array">
                <item name="Hyva_VendorModule" xsi:type="boolean">true</item>
            </argument>
        </arguments>
    </type>
</config>

Hyvä Config Registration Observer

For compatibility modules that have registered themselves using the Hyvä config registration observer, they can be removed from the hyva-themes.json file by disabling that observer in frontend/events.xml.

<?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">
        <!--
        Replace {{OBSERVER_NAME_HERE}} with the name of the observer that performs the registration.
        Convention suggests this is simply the name of the compatibility module however we recommend double-checking
        this to ensure you are using the correct name as there is no guarantee this convention is adhered to.
        -->
        <observer name="{{OBSERVER_NAME_HERE}}" disabled="true"/>
    </event>
</config>

Some modules may use BOTH methods...

In those cases, both methods of removing them from the file are required.

Since release 1.1.3 of hyva-themes/magento2-compat-module-fallback

Before that version, excluding a module required disabling it completely.

Module tailwind.config.js merging

Adding a module to the tailwind purge config

1. Create the tailwind.config.js file

Tailwind CSS v2 or v3?

Using require() inside a module

2. Add the module to the app/etc/hyva-themes.json file

The app/etc/hyva-themes.json file

Registering a module for inclusion in hyva-themes.json

Removing Modules from hyva-themes.json

Compatibility Module Registry

Hyvä Config Registration Observer

1. Create the `tailwind.config.js` file

Using `require()` inside a module

2. Add the module to the `app/etc/hyva-themes.json` file

The `app/etc/hyva-themes.json` file

Registering a module for inclusion in `hyva-themes.json`

Removing Modules from `hyva-themes.json`