Table of Contents & Menu
On this page
Navigation

Using Hyvä Modules

What is Hyvä Modules?

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

It automates the discovery and merging of styles and configurations from Hyvä-compatible modules into your theme.

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

It also provides helpers for advanced theming, such as using CSS variables in your Tailwind configuration.

Core Features

Support for Compatibility modules

npx hyva-sources replaces `mergeTailwindConfig` and `postcssImportHyvaModules` (from Hyvä 1.3.x) for Tailwind v4 projects. It generates `generated/hyva-source.css` from Hyvä-compatible modules.

To run it, use: npx hyva-sources.

It uses `app/etc/hyva-themes.json` (like its predecessors) to create a CSS file with Tailwind v4 syntax for module imports.

Exclude Magento modules from Tailwind compilation using `hyva.config.json`.

Similar to `postcssImportHyvaModules` (Hyvä 1.3.x), you provide a list of modules to exclude.

This command offers more flexibility, supporting not only Hyvä-compatible modules but also extra paths. For instance, it can automatically include parent themes, removing the need for manual inclusion.

Example `hyva.config.json` demonstrating `include` and `exclude` options:

{
    "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.

For Tailwind v2 and v3, this is handled by `mergeTailwindConfig` and `postcssImportHyvaModules`.

mergeTailwindConfig

Used in Tailwind v2 and v3, this function merges Tailwind configurations from Hyvä-compatible modules into your theme.

To use, import `mergeTailwindConfig` into `tailwind.config.js` and wrap your exported config object with it:

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

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

postcssImportHyvaModules

This complements `mergeTailwindConfig` by handling CSS imports.

To use, import `postcssImportHyvaModules` into `postcss.config.js` and add it to your plugin list.

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, refer to:

CSS Variables

Tailwind v4 supports CSS variables by default, ready for immediate use.

For Tailwind v2 and v3, use `twProps` and `twVar` functions in `tailwind.config.js` to add CSS variables.

A dedicated page explains how to add twProps and twVar functions to your Tailwind v3 config.

For broader browser support, see 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.

Hyvä provides a solution to integrate Design Tokens into TailwindCSS.

First, export tokens from your design system. For tools like Token Studio for Figma, consult their documentation for export instructions.

Next, place the exported token file in your theme directory. Then, run `hyva-tokens` to generate a CSS file for your theme.

For detailed instructions, see the `hyva-tokens` documentation.