The hyva-sources command

The hyva-sources command streamlines Tailwind v4 configuration by replacing older mergeTailwindConfig and postcssImportHyvaModules JS functions. It generates a generated/hyva-sources.css file in your theme, consolidating all supported sources from Hyvä-compatible modules.

Run the command:

npx hyva-sources

How It Works

hyva-sources identifies modules for compilation using app/etc/hyva-themes.json. Unlike previous versions that merged JavaScript configurations, it generates a CSS file. This shift aligns with Tailwind v4's CSS-first configuration approach.

For details on Tailwind v4's CSS-first configuration, see the TailwindCSS v4 release blog post.

The generated CSS file includes @source directives for module phtml and xml files, automatically detecting modules with a tailwind.config.js. It also adds @import statements for any tailwind-source.css files found in Hyvä-compatible modules.

Tailwind v4 Hyvä-Compatible Modules

For modules utilizing Tailwind v4 features or requiring explicit control over source paths, a dedicated approach is recommended. While older import methods offer backward compatibility, they may not support all Tailwind v4 features.

Achieve full Tailwind v4 compatibility by adding a module.css file to your module's tailwind directory.

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

This module.css file acts as the single source of truth for your module, managing both @source and @import directives for CSS logic. The hyva-sources command intelligently recognizes and prioritizes this file, ignoring legacy configurations.

Including Extra Paths

hyva-sources offers the flexibility to include paths from any location within your project, including parent themes.

To add an include path, specify it relative to your Magento 2 root in your hyva.config.json file. hyva-sources will then correctly resolve the path based on your theme's structure.

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

Excluding Hyvä-Compatible Modules

Exclude modules by configuring your hyva.config.json file. (Previous Hyvä versions used PostCSS for exclusion.)

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