Skip to content

Using Hyvä Modules

What is Hyvä Modules?

@hyva-themes/hyva-modules is an npm package that extends TailwindCSS with several powerful features designed to streamline theme development.

Its primary function is to automate the discovery and merging of styles and configurations from third-party Hyvä-compatible modules directly into your theme.

This mimics the convenience of Magento 2's traditional LessCSS compilation but is tailored for the modern CSS toolchain.

This package also includes helpers for advanced theming techniques, like using CSS variables within your Tailwind configuration.

Core Features

Support for Compatibility modules

This handled by the mergeTailwindConfig and postcssImportHyvaModules functions.

mergeTailwindConfig

This function is used in Tailwind v2 and v3 for merging Tailwind configurations from Hyvä-compatible modules into your theme.

To use this module, import mergeTailwindConfig into your tailwind.config.js and wrap the exported module object in this function:

const { mergeTailwindConfig } = require('@hyva-themes/hyva-modules');

module.exports = mergeTailwindConfig({
// Your theme's Tailwind config here...
});

postcssImportHyvaModules

This is complementary to mergeTailwindConfig, but for CSS.

To use this module, import postcssImportHyvaModules into your postcss.config.js and include it in the list of plugins.

Important

The hyva-modules plugin must be placed before the postcss-import and tailwindcss/nesting plugins.

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

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

for a full explanation please see the dedicated docs on this at:

hyva-sources is the replacement for mergeTailwindConfig and postcssImportHyvaModules in Tailwind v4 projects. This command will create a generated/hyva-source.css in your project based on the Hyvä-compatible modules.

To run it, use: npx hyva-sources.

This uses the same app/etc/hyva-themes.json file as mergeTailwindConfig and postcssImportHyvaModules and creates a CSS file using the Tailwind v4 syntax for importing and sourcing the module files.

Since this is now handled by this command, we have moved the exclusion of modules to hyva.config.json.

Just as with postcssImportHyvaModules, you provide a list of modules you want to exclude.

Since we have a bit more freedom, this command is not just for Hyvä-compatible modules. You can even include extra paths. For example, you don't need to include the parent theme manually; you can let this command handle that for you.

Here is an example config where you can see the exclude and include options in action:

{
    "tailwind": {
        "include": [
            { "src": "app/code/Acme/hyva-module" },
            { "src": "vendor/hyva-themes/magento2-default-theme" }
        ],
        "exclude": [
            { "src": "vendor/hyva-themes/magento2-hyva-checkout/src" }
        ]
    }
}

For more information see the dedicated docs for hyva-sources.

CSS Variables

With Tailwind v4, CSS variables are supported by default and can be used out of the box.

For Tailwind v2 and v3, you need to use the twProps and twVar functions in your tailwind.config.js to add CSS variables.

We have a complete page explaining how to add twProps and twVar functions to the Tailwind Config.

If you are looking for broader browser support, please check the first method on the same page.

Design Tokens

Important

If you're not sure what Design Tokens are, please read the dedicated page on what Design Tokens are before continuing.

We offer a solution for integrating Design Tokens into TailwindCSS.

First, export your tokens from your preferred design system. If you're using a tool like Token Studio for Figma, please refer to its documentation for instructions on how to export your tokens.

Next, add the exported token file to your theme directory. Then, run the hyva-tokens command to generate a CSS file that can be imported into your theme.

For more in-depth instructions and additional information, please see the dedicated documentation for hyva-tokens.