Table of Contents & Menu
On this page
Navigation

TailwindCSS Troubleshooting

Missing CSS or Build Failures

@import is not found with Tailwind v4

Tailwind CSS v4 has stricter path resolution for @import statements. This can cause build errors if you use non-standard import paths for local files.

Fix: Use an explicit relative path (./ or ../) for all local CSS file imports.

Incorrect (Tailwind v3 compatible, not v4):

/* This works with Tailwind v3, but not v4! */
@import "acme/file.css";

Correct (explicitly relative path):

/* To import a local file, start the relative path with ./ or ../ */
@import "./acme/file.css";

Starting relative paths for @import with ./ or ../ works with Tailwind v3 and v4!

Unknown at rule: @screen on Tailwind v4 builds

Tailwind v4 removed the @screen directive. If your build warns about @screen md (e.g., in Hyvä Checkout CSS), you must update your code.

Fixes:

  • Hyvä Themes 1.4+: Replace @screen md { ... } with the new breakpoint variant syntax (e.g., @variant md { ... } or md: for utilities). Refer to Tailwind docs: https://tailwindcss.com/docs/adding-custom-styles#using-variants.
  • Hyvä Checkout: Upgrade to version 1.3.6 or newer for Tailwind v4-compatible CSS. Older versions will show this warning.

.gitignore conflict with Tailwind v4 @source

Tailwind v4's @source directive respects .gitignore patterns. This can cause issues if your .gitignore uses an "allow-list" approach (ignoring everything, then un-ignoring specific paths).

For example, a .gitignore like this:

# TW4 incompatible example:
*
!app/
!README.md

The * pattern ignores all files, including source files in vendor/hyva-themes/magento2-default-theme. This prevents Tailwind v4 from scanning necessary files, leading to missing styles and a broken build.

Solution: Use a "Deny-List" .gitignore

Switch to a "deny-list" approach: explicitly list only the files and directories to ignore. This ensures Tailwind v4 can correctly scan your project and resolve @source paths.

Example Tailwind v4 compatible .gitignore

The official Magento 2 .gitignore file is a good starting point, following best practices.

/.buildpath
/.cache
/.metadata
/.project
/.settings
/.vscode
atlassian*
/nbproject
/robots.txt
/pub/robots.txt
/sitemap
/sitemap.xml
/pub/sitemap
/pub/sitemap.xml
/.idea
/.gitattributes
/app/config_sandbox
/app/etc/config.php
/app/etc/env.php
/app/code/Magento/TestModule*
/lib/internal/flex/uploader/.actionScriptProperties
/lib/internal/flex/uploader/.flexProperties
/lib/internal/flex/uploader/.project
/lib/internal/flex/uploader/.settings
/lib/internal/flex/varien/.actionScriptProperties
/lib/internal/flex/varien/.flexLibProperties
/lib/internal/flex/varien/.project
/lib/internal/flex/varien/.settings
/node_modules
/.grunt
/Gruntfile.js
/package.json
/.php_cs
/.php_cs.cache
/.php-cs-fixer.php
/.php-cs-fixer.cache
/grunt-config.json
/pub/media/*.*
!/pub/media/.htaccess
/pub/media/attribute/*
!/pub/media/attribute/.htaccess
/pub/media/analytics/*
/pub/media/catalog/*
!/pub/media/catalog/.htaccess
/pub/media/customer/*
!/pub/media/customer/.htaccess
/pub/media/downloadable/*
!/pub/media/downloadable/.htaccess
/pub/media/favicon/*
/pub/media/import/*
!/pub/media/import/.htaccess
/pub/media/logo/*
/pub/media/custom_options/*
!/pub/media/custom_options/.htaccess
/pub/media/theme/*
/pub/media/theme_customization/*
!/pub/media/theme_customization/.htaccess
/pub/media/wysiwyg/*
!/pub/media/wysiwyg/.htaccess
/pub/media/tmp/*
!/pub/media/tmp/.htaccess
/pub/media/captcha/*
/pub/media/sitemap/*
!/pub/media/sitemap/.htaccess
/pub/static/*
!/pub/static/.htaccess

/var/*
!/var/.htaccess
/vendor/*
!/vendor/.htaccess
/generated/*
!/generated/.htaccess
.DS_Store

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

Disabling Core Plugins in Tailwind 4

Tailwind CSS v4 no longer supports disabling core plugins via the configuration file's corePlugins object (e.g., setting a plugin to false), a feature available in v3.

A community-found, undocumented workaround using @source not inline("class-name") can prevent some utilities (like container) from being included in the final CSS. However, this method is incomplete, does not allow replacing disabled utilities with custom versions, and may break in future updates. It also doesn't work for all core plugins.

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

For more context, see the Tailwind CSS GitHub discussion (16132).