Hyvä Sources

TailwindCSS v4 Only

hyva-sources is designed exclusively for TailwindCSS v4 projects.

Experimental

This feature is currently experimental and is primarily offered to support Hyvä UI. Many modules, including some of our own, are not yet compatible with Tailwind v4. Use this feature only if you are familiar with Tailwind v4 and understand the potential compatibility issues.

hyva-sources is the designated replacement for mergeTailwindConfig and postcssImportHyvaModules in Tailwind v4 projects. It generates a generated/hyva-sources.css file in your theme, which includes all supported Hyvä-compatible modules.

To run it, use the following command:

npx hyva-sources

How It Works

hyva-sources uses the same app/etc/hyva-themes.json file as mergeTailwindConfig and postcssImportHyvaModules to identify the list of modules. However, instead of merging JavaScript configurations, it generates a CSS file. This is because Tailwind v4 uses a CSS file for its configuration, rather than a JavaScript file.

For more information on Tailwind v4's CSS-first configuration, please refer to the TailwindCSS v4 release blog post.

The generated file will contain @source directives for each module's phtml and xml files. This is done automatically if the module contains a tailwind.config.js file. If a Hyvä-compatible module includes a tailwind-source.css file, this script will also add the appropriate @import statement.

Tailwind v4 Hyvä-Compatible Modules

If your module needs to use Tailwind v4 features or you want to control the source paths, a different approach is required. While older import methods are maintained for backward compatibility, they may not work for all Tailwind v4 features.

For full Tailwind v4 compatibility, you can add a module.css file to your module's tailwind directory.

If your module is not yet Hyvä-compatible, please refer to the documentation on how to make your module Hyvä-compatible.

This module.css file will handle both the @source and @import directives for your CSS logic. hyva-sources is smart enough to recognize this file and use it as the single source of truth for your module, ignoring other legacy configuration files.

Including Extra Paths

A significant advantage of hyva-sources is its ability to include paths from anywhere in your project, including a parent theme.

To add a new include path, specify the path relative to your Magento 2 root in your hyva.config.json file. hyva-sources will then generate the correct path based on your theme's structure.

Example: Including the Parent Theme

{
    "tailwind": {
        "include": [
            { "src": "vendor/hyva-themes/magento2-default-theme" }
        ]
    }
}

Excluding Hyvä-Compatible Modules

Excluding modules is similar to the previous method but is now handled within the hyva.config.json file instead of the PostCSS configuration.

Info

For information on the older method, please refer to the Overriding Module CSS documentation.

Example: Excluding Auto-Imported Modules

{
    "tailwind": {
        "exclude": [
            { "src": "vendor/hyva-themes/magento2-hyva-checkout/src" }
        ]
    }
}