Tailwind v4: @layer components is a native CSS passthrough, so its classes are never tree-shaken (unlike @utility)

[zie1ony]

From Human

My agent was struggling with frontend for unusually long time until it gets it right.
I asked for a report. Let me know if that even makes sense.

From AI

In v3, @layer components was a Tailwind directive: contents were registered with the engine and purged if unused. In v4 it is emitted as a plain native CSS cascade layer and its contents are always shipped, used or not. @apply still works inside it, so a v3-era stylesheet migrates with no warning and no error — it just silently ships dead CSS.
The v4-idiomatic @utility is still tree-shaken. Same build, same file:

@layer components {
  .probe-never-used { @apply text-destructive; }
}
@utility probe-utility-unused {
  color: red;
}

Neither class is referenced by any template. After vite build with @tailwindcss/vite 4.3.3:

• .probe-never-used — present in the output CSS
• probe-utility-unused — absent
  Established by grepping the built CSS for each probe, adding and removing them one at a time. The emitted layer order is properties, theme, base, components, utilities, with components a real @layer components{...} block in the output.
  Practical consequences:
• @apply inside @layer components compiles correctly in v4 — multi-class applies, variants (hover:, focus-visible:, disabled:), and opacity modifiers (bg-primary/85) all expand as expected. If you want a handful of shared widget classes, the v3 pattern is not broken.
• But it is no longer dead-code eliminated. A large inherited @layer components block carried over from v3 ships in full. Anyone auditing v4 bundle size should check there first.
• Choosing between them is a real trade-off, not just style: @utility gets tree-shaking and participates in variant composition, while @layer components gives you plain low-specificity classes that always exist — which is what you want if the class is referenced from somewhere the scanner cannot see (server-rendered markup, string-built class names).

[wongjn]

That all makes sense. @layer components is no longer "special" in v4. Utilities and components kind of lose meaning in v4 because you register class names the same way via @utility.

[zie1ony]

Cool. Out of pure curiosity. Is this something you would work on soon or it is low priority? I try to asses how useful is this AI-generated report.

[wongjn]

When you ask whether it would be worked on soon, what are you referring to? It all seems to work as intended.

[zie1ony]

You are right. All good.

[SirHegel]

Your report is correct, and the probe methodology is the right way to have established it. It is worth stating the underlying reason plainly, because it explains why this is not a bug and why it will not be fixed.

@layer means something different in v4

In v3, @layer was a Tailwind directive. The engine parsed the block, registered its contents, and emitted only what your templates referenced.

In v4, @layer is the native CSS at-rule from the cascade layers spec. Tailwind does not own it any more. A native @layer block is ordinary CSS that happens to be assigned to a layer, and ordinary CSS is not something a content scanner can decide to drop — there is no name registered anywhere to match against your templates.

@utility is what replaced the registration half of the old behaviour. That is why your two probes behave differently: probe-utility-unused is a registered name the engine can match and discard; .probe-never-used is just a rule.

Why the migration is silent

This is the part that makes it costly rather than merely surprising. @apply still works inside a native @layer block, so a v3 stylesheet keeps compiling, keeps producing the right visual result, and keeps passing whatever tests you have. Nothing in the pipeline has any reason to warn you. The only observable difference is bundle size, which is exactly the signal nobody looks at during a framework migration.

Auditing an existing stylesheet

Rather than probing class by class, you can get the whole list in one pass. Every selector declared inside a @layer components block that does not appear in your templates is dead weight:

# every class defined inside @layer components
rg -oN --multiline '@layer\s+components\s*\{(?s).*?\}' src/**/*.css \
  | rg -o '\.[a-zA-Z0-9_-]+' | sort -u > /tmp/declared.txt

# every class actually referenced in templates
rg -oN '(?:class|className)="[^"]*"' src --glob '*.{html,jsx,tsx,vue,svelte}' \
  | rg -o '[a-zA-Z0-9_-]+' | sort -u > /tmp/used.txt

comm -23 /tmp/declared.txt /tmp/used.txt

Anything that comes out of that comm is shipping and unused. Treat it as the migration worklist.

What to convert them to

For anything that is genuinely a utility — one concern, composable, meant to be applied from markup — @utility restores the v3 behaviour you expected:

@utility card-surface {
  @apply rounded-lg border bg-white shadow-sm;
}

For anything that is genuinely a component — a selector with descendants, states, or structure that would be awkward as a single utility — plain CSS outside any Tailwind layer is fine, but then ship it deliberately. The problem is not that component CSS exists; it is that it was sitting in a block whose name implied it would be pruned.

On the report itself

Worth saying: the probe pair, the single-variable isolation, and grepping the built output rather than trusting the dev server is a better bug report than most. It is the difference between "unused CSS seems to ship" and a finding someone can act on in one read.

[shiliaiwei]

Yes, the report makes 100% sense and is completely accurate.

In v4, @layer was intentionally aligned with the native CSS Cascade Layers spec. Because it's now standard CSS, the engine treats it as a passthrough and won't scan your templates to purge unused rules inside it.

@utility is the v4 replacement for custom classes that need to be tracked by the Oxide/Rust scanner, tree-shaken, and wired up to variant modifiers (hover:, dark:, etc.).

So migrating v3 custom component classes from @layer components to @utility is the intended path if you want zero dead CSS.