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. -
Import the module in the themes
tailwind.config.js
file. -
Wrap the value assigned to
module.exports
in a function call tohyvaModules.mergeTailwindConfig
.
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:
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:
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
:
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
(only before Magento 2.4.7)bin/magento module:enable
bin/magento module:disable
The file can also be explicitly generated by the command
With Hyvä version 1.14 of with 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
(only before Magento 2.4.7)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.
This can be achieved by passing the module name to the Hyva\CompatModuleFallback\Observer\HyvaThemeHyvaConfigGenerateBefore
class's exclusions
array in di.xml
.
<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>
Since release 1.1.3 of hyva-themes/magento2-compat-module-fallback
Before that version, excluding a module required disabling it completely.