Re-enable: Only expose used CSS variables

[philipp-spiess]

This PR re-enables the changes necessary to remove unused theme variables and keyframes form your CSS.

This change was initially landed as #16211 and then later reverted in #16403 because we found some unexpected interactions with using @apply and CSS variables in multi-root setups like CSS modules or Vue inline <style> blocks that were no longer seeing their required variables defined.

This issue is fixed by now ensuring that theme variables that are defined within an @reference "…" boundary will still be emitted in the generated CSS when used (as this would otherwise not generate a valid stylesheet).

So given the following input CSS:

@reference "tailwindcss";
.text-red {
  @apply text-red-500;
}

We will now compile this to:

@layer theme {
  :root, :host {
    --text-red-500: oklch(0.637 0.237 25.331);
  }
}
.text-red {
  color: var(--text-red-500);
}

This PR also improves the initial implementation to not mark theme variables as used if they are only used to define other theme variables. For example:

@theme {
  --font-sans:
    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
    'Noto Color Emoji';
  --font-mono:
    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New',
    monospace;

  --default-font-family: var(--font-sans);
  --default-mono-font-family: var(--font-mono);
}

.default-font-family {
  font-family: var(--default-font-family);
}

This would be reduced to the following now as --font-mono is only used to define another variable and never used outside the theme block:

:root, :host {
  --font-sans:
    ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol',
    'Noto Color Emoji';
  --default-font-family: var(--font-sans);
}

.default-font-family {
  font-family: var(--default-font-family);
}

Test plan

• See updated unit and integration tests
• Validated it works end-to-end by using a SvelteKit example

[moatorres]

Great work, @philipp-spiess! Am I right to assume that this will be included on v4.0.8?

[philipp-spiess]

@moatorres Yep. We're preparing the release right now so hopefully it's out in a couple of hours 👍

[dpi]

Thanks @philipp-spiess !

[doits]

Sorry for hijacking this, but how can I force to output some of the default theme variables even if they are not detected automatically? E.g. how can I always emit all the--color-* variables (because I use them in other places dynamically where the values come from the database and cannot be inferred just by scanning the code)?

[wenbei]

@doits You can use the new static keyword, see the original #16211

[gene-git]

Should 4.0.8 have fixed #16725 ?

[wongjn]

No, I think this PR is what is causing #16725.

[gene-git]

Thanks @wongjn - makes more sense :)

I downgraded to 4.0.7 but problem remains. I will try going back to 4.0.6

[gene-git]

4.0.6 has same problem. 4.0.6 with postcss rolled back to 8.5.2 same problem as well.

Now I am perplexed. This should be same as production server is running.

Suggestions?

[wongjn]

Try checking you have successfully downgraded, via npm ls tailwind - you may have different versions installed as deeper dependencies.

[gene-git]

you're correct - 4.0.8 is pulled in and visible in package-lock.json.

I deleted node_modules and .next and package-lock.json and package.json has 4.0.6

grep tailwindcss package.json
    "@tailwindcss/typography": "^0.5.16",
    "@tailwindcss/postcss": "^4.0.6",
    "tailwindcss": "^4.0.6"

Yet after doing npm install it shows:

$ npm ls tailwindcss

├─┬ @tailwindcss/postcss@4.0.8
│ ├─┬ @tailwindcss/node@4.0.8
│ │ └── tailwindcss@4.0.8 deduped
│ └── tailwindcss@4.0.8 deduped
├─┬ @tailwindcss/typography@0.5.16
│ └── tailwindcss@4.0.8 deduped
└── tailwindcss@4.0.8

Hmm. My ignorance clearly showing - what is the correct way to get 4.0.6 ?

Okay this seems to work:

npm install @tailwindcss/postcss@4.0.6 @tailwindcss/node@4.0.6 tailwindcss@4.0.6

Now its back to 4.0.6 and builds again.

Thank you for your help @wongjn.

[wongjn]

If you're using git, you could revert package.json and package-lock.json to a commit before 4.0.8 was installed. Otherwise, you could force 4.0.7 or 4.0.6 like:

npm install @tailwindcss/postcss@4.0.6 tailwindcss@4.0.6

[gene-git]

Thanks @wongjn - yep I'm using git so for sure I can go back to the production tag.

[gene-git]

Does anyone have thoughts on how to fix #16725 ?

[doits]

@doits You can use the new static keyword, see the original #16211

@wenbei thanks for the tip, I tried it but got stuck at how to name the variable to include all colors, e.g. tried this:

@theme static {
  --color-*: <XXX>;
}

with <XXX> as static, default, initial and inherit (my four best guesses) – it failed to compile with each, for example:

Error: Invalid theme value static for namespace --color-*

Or must I copy all the variables from the docs and put them there explicitly? I guess this works in the meantime but then I won't get any update if the theme is changed 🤔

[doits]

... just found out in #16514 how to include all variables:

@import "tailwindcss" theme(static);

Works for my use case.

Though I'd still be interested if you can make only some of the variables static (e.g. only all --color-* ones).