TailwindCSS Troubleshooting

Missing CSS or Build Failures

@import is not found with Tailwind v4

In Tailwind CSS v4, the path resolution for @import statements is stricter to better align with the modern CSS specification. This can cause build errors if you are using older, non-standard import paths for local files.

To fix this, you must use an explicit relative path (./ or ../) for any local CSS files you import.

/* If you were importing a local file, ensure it's a relative path */
@import "./acme/file.css";

.gitignore Conflict with Tailwind v4 @source

A common issue arises if your project's .gitignore file uses a broad wildcard (*) to ignore all files and then selectively un-ignores specific files (an "allow-list" approach).

Tailwind v4's @source directive respects the .gitignore file.

When it encounters the * pattern, it treats all files as ignored, including source files from other themes located in the vendor/ directory (e.g., vendor/hyva-themes/magento2-default-theme).

This prevents Tailwind from bundling the necessary CSS, leading to a broken build process.

Solution: Use a "Deny-List" .gitignore

To resolve this, switch to a "deny-list" approach in your .gitignore. Instead of ignoring everything, explicitly list only the files and directories that should be ignored.

This ensures that tools like Tailwind can correctly scan the project and resolve @source paths.

A great starting point is the official Magento 2 .gitignore file, which is well-maintained and follows best practices.

For more technical details, see the related discussion (18303) on the Tailwind CSS GitHub.

Disabling Core Plugins in Tailwind 4

A significant change in Tailwind CSS v4 is the removal of the ability to disable core plugins directly from the configuration file.

In v3, you could disable a plugin by setting it to false in the corePlugins object; this is no longer supported in v4.

A community-discovered workaround using @source not inline("class-name") exists, which can prevent some utilities (like container) from being included in the final CSS. However, this method does not allow you to replace the disabled utility with a custom version.

This workaround should be treated with caution as it is not a complete solution.

It does not work for all core plugins.

For example, disabling foundational plugins like preflight requires a different, more complex setup as detailed in the official Tailwind Docs: Disabling Preflight.

For more background on this topic, see the related discussion (16132) on the Tailwind CSS GitHub.