[v4] Unused keyframes are included in generated CSS

[heidkaemper]

What version of Tailwind CSS are you using?

v4.0.0

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

Tailwind CLI

What version of Node.js are you using?

v21.6.1

What operating system are you using?

Linux / macOS

Reproduction URL

Check out this repo:
https://github.com/heidkaemper/tailwind4-keyframes-issue

Run the Tailwind CLI with npm run dev

Describe your issue

I've added a custom animation just as described in the docs:
https://tailwindcss.com/docs/theme#defining-animation-keyframes

But although the animation is not used at all, the CSS property and keyframes are included in the generated CSS file:

/*! tailwindcss v4.0.0 | MIT License | https://tailwindcss.com */
@layer theme, base, components, utilities;
@layer theme {
  :root {
    ...

    --animate-fade-in-scale: fade-in-scale 0.3s ease-out;
  }
}

...

@keyframes fade-in-scale {
  0% {
    opacity: 0;
    transform: scale(0.95);
  }
  100% {
    opacity: 1;
    transform: scale(1);
  }
}

The same goes for the default animations spin, ping, pulse and bounce. CSS properties and keyframes are included, only utility classes are not.

I would expect --animate-* variables and keyframes to only be included in the generated CSS file if they are actually used.

[philipp-spiess]

Hey! This is expected behavior. We currently include all keyframes as long as we also emit a CSS --animate-* variable that uses the keyframes. CSS theme variables are currently always emitted too, since these usually are not growing unbound and it might be useful to have access to them from the client (e.g. if you want styles outside of Tailwind CSS being able to read these variables). That's something that we might reconsider in the future though

For now, if you don't need a theme variable I suggest you use the initial syntax to remove it: https://tailwindcss.com/docs/theme#overriding-the-default-theme

[heidkaemper]

Hmm, that's a bit unfortunate. Assume you have a design system with 20 or even more default animations. With v3 this was no problem, with v4 all keyframes are written to the CSS file. Regardless of whether the animation is actually used or not.

Thanks for the explanation though!

You should probably edit the docs. Because here it explicitly states that the keyframes do not end up in the generated CSS:
https://tailwindcss.com/docs/theme#defining-animation-keyframes