From 5e9f66e4284164c62e80d74e69e0cbd8d9c645cc Mon Sep 17 00:00:00 2001 From: Robin Malfait Date: Wed, 17 Jun 2026 15:23:20 +0200 Subject: [PATCH] Ensure `@variant` can be used in JS based APIs (#20252) This PR doesn't fix any issues, but it does add an integration test (as a regression test) to make sure that `@variant` with default variants and custom variants can be used inside of JS based plugin APIs. In Tailwind CSS v4.3.1 we introduced a PR that handles `@variant` in the `addBase` Plugin API (https://github.com/tailwindlabs/tailwindcss/pull/19480). This was a bit of an older PR, but the tests made sense, so it was merged. However, by introducing that PR, we introduced a bug that the `@variant` was handled too early. If you added custom variants later _and_ used it in the `addBase`, then you would get an error since the variant isn't available (yet). That issue was fixed by https://github.com/tailwindlabs/tailwindcss/pull/20247 Now the question remains, why did we even have the original PR when it already worked? The use case we had was using `@variant` as part of the `@tailwindcss/typography` plugin configuration for one of our templates. I was indeed able to reproduce the issue where `@variant lg` was seen in the output CSS file. Turns out that this template was using `@tailwindcss/typography` + `@variant` in the configuration, but it was also using Tailwind CSS v4.1.15. Upgrading to the latest version automagically fixed the issue we had. This is also the behavior you can see in the integration test. The correct behavior was introduced in an even older PR https://github.com/tailwindlabs/tailwindcss/pull/19263 All that said, everything should work in the next release related to `@variant` usages inside JS based APIs. **Tiny improvement** While debugging what's going on, I noticed that we looped over the AST to get some nodes out and we did that twice. This PR also improves that by re-using the same list of nodes instead of computing it twice. This won't have a huge impact, but it happened while compiling every single utility which is not ideal. ## Test plan 1. All tests should pass 2. I can't see `@variant` in the output CSS file Input: image Before: image After: image --- integrations/cli/plugins.test.ts | 76 +++++++++++++++++++++++ packages/tailwindcss/src/design-system.ts | 12 ++-- 2 files changed, 80 insertions(+), 8 deletions(-) diff --git a/integrations/cli/plugins.test.ts b/integrations/cli/plugins.test.ts index b61d693f2..4cda7955a 100644 --- a/integrations/cli/plugins.test.ts +++ b/integrations/cli/plugins.test.ts @@ -48,6 +48,82 @@ test( }, ) +test( + 'builds the `@tailwindcss/typography` plugin utilities with `@variant` usages', + { + fs: { + 'package.json': json` + { + "dependencies": { + "@tailwindcss/typography": "^0.5.14", + "tailwindcss": "workspace:^", + "@tailwindcss/cli": "workspace:^" + } + } + `, + 'index.html': html` +
+

Headline

+

+ Until now, trying to style an article, document, or blog post with Tailwind has been a + tedious task that required a keen eye for typography and a lot of complex custom CSS. +

+
+ `, + 'src/index.css': css` + @import 'tailwindcss/utilities'; + @theme { + --breakpoint-sm: 640px; + } + @plugin '@tailwindcss/typography'; + @config '../tailwind.config.js'; + @custom-variant custom (&.custom); + `, + 'tailwind.config.js': ts` + module.exports = { + theme: { + typography: ({ theme }) => ({ + custom: { + css: { + hr: { + '--x': '1', + '@variant sm:custom': { + '--x': '2', + }, + }, + }, + }, + }), + }, + } + `, + }, + }, + async ({ fs, exec, expect }) => { + await exec('pnpm tailwindcss --input src/index.css --output dist/out.css') + + // We don't want to see `@variant` in the output + let contents = await fs.read('dist/out.css') + expect(contents).not.toContain('@variant') + + expect(await fs.dumpFiles('dist/out.css')).toMatchInlineSnapshot(` + " + --- dist/out.css --- + .prose-custom { + :where(hr):not(:where([class~="not-prose"], [class~="not-prose"] *)) { + --x: 1; + @media (width >= 640px) { + &.custom { + --x: 2; + } + } + } + } + " + `) + }, +) + test( 'builds the `@tailwindcss/forms` plugin utilities', { diff --git a/packages/tailwindcss/src/design-system.ts b/packages/tailwindcss/src/design-system.ts index 975e59e9a..71d506938 100644 --- a/packages/tailwindcss/src/design-system.ts +++ b/packages/tailwindcss/src/design-system.ts @@ -84,20 +84,16 @@ export function buildDesignSystem( let ast = compileAstNodes(candidate, designSystem, flags) try { + let nodes = ast.map((value) => value.node) + // Arbitrary values (`text-[theme(--color-red-500)]`) and arbitrary // properties (`[--my-var:theme(--color-red-500)]`) can contain function // calls so we need evaluate any functions we find there that weren't in // the source CSS. - substituteFunctions( - ast.map(({ node }) => node), - designSystem, - ) + substituteFunctions(nodes, designSystem) // JS plugins might contain an `@variant` inside a generated utility - substituteAtVariant( - ast.map(({ node }) => node), - designSystem, - ) + substituteAtVariant(nodes, designSystem) } catch (err) { // If substitution fails then the candidate likely contains a call to // `theme()` that is invalid which may be because of incorrect usage,