@tailwindcss/vite skips CSS files that only use @variant (feature detection gap)

[remorses]

What version of Tailwind CSS are you using?

v4.2.2

What build tool (or framework if it abstracts the build tool) are you using?

Vite 8.0.8 with @tailwindcss/vite

What version of Node.js are you using?

v24.14.0

What browser are you using?

Chrome

What operating system are you using?

macOS

Reproduction URL

https://github.com/remorses/tailwind-variant-bug

Describe your issue

A CSS file that only uses @variant (no @apply, theme(), or utility classes) is silently skipped by @tailwindcss/vite. The @variant directive is passed through raw to the browser, which drops it as an unknown at-rule.

Reproduction — two CSS files in a Vite project:

/* main.css — Tailwind entry */
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));

/* overrides.css — imported via JS: import './overrides.css' */
:root {
  @variant dark {
    --background: var(--color-neutral-950);
  }
}

overrides.css is never processed by Tailwind. The @variant dark rule is served raw to the browser and silently discarded. Adding @apply hidden to a dummy class in the same file makes Tailwind process it and @variant starts working.

Root cause — the feature detection check in @tailwindcss/vite (line 475-481):

if (
  !(
    this.compiler.features &
    (Features.AtApply | Features.JsPluginCompat | Features.ThemeFunction | Features.Utilities)
  )
) {
  return false
}

This check doesn't include @variant (or @custom-variant). If a CSS file only uses these directives, generate() returns false and the file is treated as plain CSS.

Expected behavior — @variant should be recognized as a Tailwind feature so the file gets processed.

[wongjn]

This may not work even if @variant detection was added. This is because dark wouldn't be defined as a variant. This is because as per #16056 (comment):

The idea is that stuff like @custom-variant, @variant and @utility won't work without some reference to Tailwind CSS itself.

Thus, syntax to reference Tailwind would automatically activate the detection:

--- a/overrides.css
+++ b/overrides.css
@@ -1,3 +1,5 @@
+@reference "tailwindcss";
+
 /* This file is imported via JS (import './overrides.css').
    It only uses @variant — no @apply, theme(), or utility classes.
    @tailwindcss/vite silently skips it because @variant is not in the

[remorses]

Why not make tailwind plugin process files that contain the @variant feature? So user that forgets to add @reference will not encounter this issue. I personally didn't know about @reference

[wongjn]

Tried with the PR and does work. Whether it is intended or not, I'll delegate to the maintainers.

[RobinMalfait]

The idea here is that we try to detect if we have to run Tailwind CSS on the file, or if we can quickly bail out.

The @import "tailwindcss"; or @reference "tailwindcss"; is important if you want to include the default theme, custom @theme and other configuration that change how Tailwind CSS works.

Note that a @variant lg won't work in this case, because lg is driven by @theme values. But this is already the case right now if you use @apply flex; in a file without an import/reference, then it will work. But @apply bg-red-500; will not work.

Since you don't have a reference to the other file, it also means that the dark variant usage in the overrides.css will use the default dark implementation, not the custom one.

[RobinMalfait]

With the fix, you will get this:

:root {
  --background: white;
}
@media (prefers-color-scheme: dark) {
  :root {
    --background: var(--color-neutral-950);
  }
}

[remorses]

Thank you!