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.