Skip to content

Module tailwind-source.css merging

Modules can add CSS declarations that will be used in addition to a theme tailwind-source.css file.

This feature is provided by a npm module @hyva-themes/hyva-modules (the same npm module that also provides module tailwind.config.js merging).

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-source.css merging for 1.1.13 and older themes

  1. 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

  2. Import the module in the themes postcss.config.js file. 

    const { postcssImportHyvaModules } = require("@hyva-themes/hyva-modules");

  3. Add the postcssImportHyvaModules to the module.exports before the postcss-import plugin. 

    const { postcssImportHyvaModules } = require("@hyva-themes/hyva-modules");

module.exports = {
    plugins: [
        postcssImportHyvaModules,
        require('postcss-import'),
        // other plugins
    ]
}

The npm module also contains functionality to merge tailwind.config.js configuration from modules.

Adding a module to the tailwind CSS source

1. Create the tailwind-source.css file

For modules the tailwind-source.css file is located at view/frontend/tailwind/tailwind-source.css.

Any paths are specified relative to this file. For example, to include the modules components/widgets.css file, use

@import "components/widgets.css";

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

A modules tailwind-source.css 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.

The hyva-themes.json file is generated by the command 

bin/magento hyva:config:generate

After a compat module is installed on a Magento instance, this command should be run to add it to the tailwind build process. No manual configuration changes are required.

For more information on the hyva-themes.json file can be found on the tailwind.config.js merging documentation.

Excluding module tailwind source files from merging

Available since @hyva-themes/hyva-modules 1.0.7

The excludeDirs option is available since release 1.0.7 of the @hyva-themes/hyva-modules library.
To check the currently installed version, change into your themes' web/tailwind directory
and run npm list @hyva-themes/hyva-modules

If a modules includes CSS files with styles that don't work for your theme, a module can be excluded from the merge process on a theme level in the themes' web/tailwind/postcss.config.js file.
To do so add an excludeDirs option to the postcssImportHyvaModules plugin as shown in the following example:

const { postcssImportHyvaModules } = require("@hyva-themes/hyva-modules");

module.exports = {
    plugins: [
        postcssImportHyvaModules({
            excludeDirs: ["vendor/hyva-themes/magento2-hyva-checkout/src"],
        }),
        require("postcss-import"),
        require("tailwindcss/nesting"),
        require("tailwindcss"),
        require("autoprefixer"),
    ],
};

The steps to override a modules CSS in a theme are:

  1. Add the module directory to the excludeDirs directive as described above.
  2. Copy the CSS files from the module to your themes web/tailwind/theme directory.
  3. Import the new files in your themes web/tailwind/tailwind-source.css file.
  4. Customize the CSS files from the module as required.
Upgrading @hyva-themes/hyva-modules

To update the library to a newer version, first change into your themes' web/tailwind directory.
To upgrade to 1.0.7 specifically, run npm upgrade @hyva-themes/hyva-modules@1.0.7
To upgrade to the latest version, run npm upgrade @hyva-themes/hyva-modules