The hyva-sources command

TailwindCSS v4 Only

hyva-sources is only available on TailwindCSS v4 projects.

The hyva-sources command replaces the mergeTailwindConfig and postcssImportHyvaModules JS functions from earlier versions in Tailwind v4 projects. It generates a generated/hyva-sources.css file in your theme, which includes all supported sources from Hyvä-compatible modules.

To run it, use the command:

npx hyva-sources

How It Works

hyva-sources uses the app/etc/hyva-themes.json file to identify the list of modules with content that should be included during compilation.
However, instead of merging JavaScript configurations, like earlier versions did, it generates a CSS file.
This is because Tailwind v4 uses a CSS file for its configuration, rather than JavaScript.

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 to include each module's phtml and xml files during the compilation.
This happens automatically for modules containing 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 a module uses Tailwind v4 features, or you want to control the included source paths, a different approach is required.
While older import methods are still supported for backward compatibility, they do not work for all Tailwind v4 features.

For full Tailwind v4 compatibility, a module.css file can be added to a 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 CSS logic. The hyva-sources command 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 handled within the hyva.config.json file (previous Hyvä versions used the PostCSS configuration).

Info

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

!!! "Example: Excluding a module"

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