Add @source inline(…) (#17147)

philipp-spiess · RobinMalfait · web-flow · commit 215f4f348bc3 · 2025-03-12T13:55:33.000Z
This PR adds a new experimental feature that can be used to force-inline utilities based on an input string. The idea is that all utilities matching the source string will be included in your CSS: ```css /* input.css */ @source inline('underline'); /* output.css */ .underline { text-decoration: underline; } ``` Additionally, the source input is brace-expanded, meaning you can use one line to inline a whole namespace easily: ```css /* input.css */ @source inline('{hover:,}bg-red-{50,{100..900..100},950}'); /* output.css */ .bg-red-50 { background-color: var(--color-red-50); } .bg-red-100 { background-color: var(--color-red-100); } .bg-red-200 { background-color: var(--color-red-200); } .bg-red-300 { background-color: var(--color-red-300); } .bg-red-400 { background-color: var(--color-red-400); } .bg-red-500 { background-color: var(--color-red-500); } .bg-red-600 { background-color: var(--color-red-600); } .bg-red-700 { background-color: var(--color-red-700); } .bg-red-800 { background-color: var(--color-red-800); } .bg-red-900 { background-color: var(--color-red-900); } .bg-red-950 { background-color: var(--color-red-950); } @media (hover: hover) { .hover\\:bg-red-50:hover { background-color: var(--color-red-50); } .hover\\:bg-red-100:hover { background-color: var(--color-red-100); } .hover\\:bg-red-200:hover { background-color: var(--color-red-200); } .hover\\:bg-red-300:hover { background-color: var(--color-red-300); } .hover\\:bg-red-400:hover { background-color: var(--color-red-400); } .hover\\:bg-red-500:hover { background-color: var(--color-red-500); } .hover\\:bg-red-600:hover { background-color: var(--color-red-600); } .hover\\:bg-red-700:hover { background-color: var(--color-red-700); } .hover\\:bg-red-800:hover { background-color: var(--color-red-800); } .hover\\:bg-red-900:hover { background-color: var(--color-red-900); } .hover\\:bg-red-950:hover { background-color: var(--color-red-950); } } ``` This feature is also compatible with the `not` keyword that we're about to add to `@source "…"` in a follow-up PR. This can be used to set up an ignore list purely in CSS. The following code snippet, for example, will ensure that the `.container` utility is never created: ```css @theme { --breakpoint-sm: 40rem; --breakpoint-md: 48rem; --breakpoint-lg: 64rem; --breakpoint-xl: 80rem; --breakpoint-2xl: 96rem; } @source not inline("container"); @tailwind utilities; ``` ## Test plan - See added unit tests - The new brace expansion library was also benchmarked against the popular `braces` library: ``` clk: ~3.96 GHz cpu: Apple M4 Max runtime: bun 1.1.34 (arm64-darwin) benchmark avg (min … max) p75 / p99 (min … top 1%) ------------------------------------------- ------------------------------- braces 31.05 ms/iter 32.35 ms █ █ (28.14 ms … 36.35 ms) 35.14 ms ██ █ ( 0.00 b … 116.45 mb) 18.71 mb ██████▁▁▁██▁█▁██▁█▁▁█ ./brace-expansion 19.34 ms/iter 21.69 ms █ (12.53 ms … 26.63 ms) 25.53 ms ▅ ▅ █ █ ( 0.00 b … 114.13 mb) 11.86 mb █▁▅▁██▁▅█▅█▅▁█▅█▅▅▁▅█ ┌ ┐ ╷┌────┬─┐ ╷ braces ├┤ │ ├─────┤ ╵└────┴─┘ ╵ ╷ ┌────┬───┐ ╷ ./brace-expansion ├────────┤ │ ├───────┤ ╵ └────┴───┘ ╵ └ ┘ 12.53 ms 23.84 ms 35.14 ms ``` --------- Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - _Experimental_: Add `any-pointer-none`, `any-pointer-coarse`, and `any-pointer-fine` variants ([#16941](https://github.com/tailwindlabs/tailwindcss/pull/16941))
 - _Experimental_: Add `user-valid` and `user-invalid` variants ([#12370](https://github.com/tailwindlabs/tailwindcss/pull/12370))
 - _Experimental_: Add `wrap-anywhere`, `wrap-break-word`, and `wrap-normal` utilities ([#12128](https://github.com/tailwindlabs/tailwindcss/pull/12128))
+- _Experimental_: Add `@source inline(…)` ([#17147](https://github.com/tailwindlabs/tailwindcss/pull/17147))
 
 ### Fixed
 
diff --git a/packages/tailwindcss/src/feature-flags.ts b/packages/tailwindcss/src/feature-flags.ts
@@ -2,5 +2,6 @@ export const enableDetailsContent = process.env.FEATURES_ENV !== 'stable'
 export const enableInvertedColors = process.env.FEATURES_ENV !== 'stable'
 export const enablePointerVariants = process.env.FEATURES_ENV !== 'stable'
 export const enableScripting = process.env.FEATURES_ENV !== 'stable'
+export const enableSourceInline = process.env.FEATURES_ENV !== 'stable'
 export const enableUserValid = process.env.FEATURES_ENV !== 'stable'
 export const enableWrapAnywhere = process.env.FEATURES_ENV !== 'stable'
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
@@ -3194,6 +3194,185 @@ describe('@source', () => {
       { pattern: './php/secr3t/smarty.php', base: '/root' },
     ])
   })
+
+  describe('@source inline(…)', () => {
+    test('always includes the candidate', async () => {
+      let { build } = await compile(
+        css`
+          @source inline("underline");
+          @tailwind utilities;
+        `,
+        { base: '/root' },
+      )
+
+      expect(build([])).toMatchInlineSnapshot(`
+        ".underline {
+          text-decoration-line: underline;
+        }
+        "
+      `)
+    })
+
+    test('applies brace expansion', async () => {
+      let { build } = await compile(
+        css`
+          @theme {
+            --color-red-50: oklch(0.971 0.013 17.38);
+            --color-red-100: oklch(0.936 0.032 17.717);
+            --color-red-200: oklch(0.885 0.062 18.334);
+            --color-red-300: oklch(0.808 0.114 19.571);
+            --color-red-400: oklch(0.704 0.191 22.216);
+            --color-red-500: oklch(0.637 0.237 25.331);
+            --color-red-600: oklch(0.577 0.245 27.325);
+            --color-red-700: oklch(0.505 0.213 27.518);
+            --color-red-800: oklch(0.444 0.177 26.899);
+            --color-red-900: oklch(0.396 0.141 25.723);
+            --color-red-950: oklch(0.258 0.092 26.042);
+          }
+          @source inline("bg-red-{50,{100..900..100},950}");
+          @tailwind utilities;
+        `,
+        { base: '/root' },
+      )
+
+      expect(build([])).toMatchInlineSnapshot(`
+        ":root, :host {
+          --color-red-50: oklch(0.971 0.013 17.38);
+          --color-red-100: oklch(0.936 0.032 17.717);
+          --color-red-200: oklch(0.885 0.062 18.334);
+          --color-red-300: oklch(0.808 0.114 19.571);
+          --color-red-400: oklch(0.704 0.191 22.216);
+          --color-red-500: oklch(0.637 0.237 25.331);
+          --color-red-600: oklch(0.577 0.245 27.325);
+          --color-red-700: oklch(0.505 0.213 27.518);
+          --color-red-800: oklch(0.444 0.177 26.899);
+          --color-red-900: oklch(0.396 0.141 25.723);
+          --color-red-950: oklch(0.258 0.092 26.042);
+        }
+        .bg-red-50 {
+          background-color: var(--color-red-50);
+        }
+        .bg-red-100 {
+          background-color: var(--color-red-100);
+        }
+        .bg-red-200 {
+          background-color: var(--color-red-200);
+        }
+        .bg-red-300 {
+          background-color: var(--color-red-300);
+        }
+        .bg-red-400 {
+          background-color: var(--color-red-400);
+        }
+        .bg-red-500 {
+          background-color: var(--color-red-500);
+        }
+        .bg-red-600 {
+          background-color: var(--color-red-600);
+        }
+        .bg-red-700 {
+          background-color: var(--color-red-700);
+        }
+        .bg-red-800 {
+          background-color: var(--color-red-800);
+        }
+        .bg-red-900 {
+          background-color: var(--color-red-900);
+        }
+        .bg-red-950 {
+          background-color: var(--color-red-950);
+        }
+        "
+      `)
+    })
+
+    test('adds multiple inline sources separated by spaces', async () => {
+      let { build } = await compile(
+        css`
+          @theme {
+            --color-red-100: oklch(0.936 0.032 17.717);
+            --color-red-200: oklch(0.885 0.062 18.334);
+          }
+          @source inline("block bg-red-{100..200..100}");
+          @tailwind utilities;
+        `,
+        { base: '/root' },
+      )
+
+      expect(build([])).toMatchInlineSnapshot(`
+        ":root, :host {
+          --color-red-100: oklch(0.936 0.032 17.717);
+          --color-red-200: oklch(0.885 0.062 18.334);
+        }
+        .block {
+          display: block;
+        }
+        .bg-red-100 {
+          background-color: var(--color-red-100);
+        }
+        .bg-red-200 {
+          background-color: var(--color-red-200);
+        }
+        "
+      `)
+    })
+
+    test('ignores invalid inline candidates', async () => {
+      let { build } = await compile(
+        css`
+          @source inline("my-cucumber");
+          @tailwind utilities;
+        `,
+        { base: '/root' },
+      )
+
+      expect(build([])).toMatchInlineSnapshot(`""`)
+    })
+
+    test('can be negated', async () => {
+      let { build } = await compile(
+        css`
+          @theme {
+            --breakpoint-sm: 40rem;
+            --breakpoint-md: 48rem;
+            --breakpoint-lg: 64rem;
+            --breakpoint-xl: 80rem;
+            --breakpoint-2xl: 96rem;
+          }
+          @source not inline("container");
+          @tailwind utilities;
+        `,
+        { base: '/root' },
+      )
+
+      expect(build(['container'])).toMatchInlineSnapshot(`""`)
+    })
+
+    test('applies brace expansion to negated sources', async () => {
+      let { build } = await compile(
+        css`
+          @theme {
+            --color-red-50: oklch(0.971 0.013 17.38);
+            --color-red-100: oklch(0.936 0.032 17.717);
+            --color-red-200: oklch(0.885 0.062 18.334);
+            --color-red-300: oklch(0.808 0.114 19.571);
+            --color-red-400: oklch(0.704 0.191 22.216);
+            --color-red-500: oklch(0.637 0.237 25.331);
+            --color-red-600: oklch(0.577 0.245 27.325);
+            --color-red-700: oklch(0.505 0.213 27.518);
+            --color-red-800: oklch(0.444 0.177 26.899);
+            --color-red-900: oklch(0.396 0.141 25.723);
+            --color-red-950: oklch(0.258 0.092 26.042);
+          }
+          @source not inline("bg-red-{50,{100..900..100},950}");
+          @tailwind utilities;
+        `,
+        { base: '/root' },
+      )
+
+      expect(build(['bg-red-500', 'bg-red-700'])).toMatchInlineSnapshot(`""`)
+    })
+  })
 })
 
 describe('@custom-variant', () => {
diff --git a/packages/tailwindcss/src/index.ts b/packages/tailwindcss/src/index.ts
@@ -26,8 +26,10 @@ import { applyVariant, compileCandidates } from './compile'
 import { substituteFunctions } from './css-functions'
 import * as CSS from './css-parser'
 import { buildDesignSystem, type DesignSystem } from './design-system'
+import { enableSourceInline } from './feature-flags'
 import { Theme, ThemeOptions } from './theme'
 import { createCssUtility } from './utilities'
+import { expand } from './utils/brace-expansion'
 import { escape, unescape } from './utils/escape'
 import { segment } from './utils/segment'
 import { compoundsForSelectors, IS_VALID_VARIANT_NAME } from './variants'
@@ -127,6 +129,8 @@ async function parseCss(
   let utilitiesNode = null as AtRule | null
   let variantNodes: AtRule[] = []
   let globs: { base: string; pattern: string }[] = []
+  let inlineCandidates: string[] = []
+  let ignoredCandidates: string[] = []
   let root = null as Root
 
   // Handle at-rules
@@ -208,15 +212,43 @@ async function parseCss(
         throw new Error('`@source` cannot be nested.')
       }
 
+      let not = false
+      let inline = false
       let path = node.params
+
+      if (enableSourceInline) {
+        if (path[0] === 'n' && path.startsWith('not ')) {
+          not = true
+          path = path.slice(4)
+        }
+
+        if (path[0] === 'i' && path.startsWith('inline(')) {
+          inline = true
+          path = path.slice(7, -1)
+        }
+      }
+
       if (
         (path[0] === '"' && path[path.length - 1] !== '"') ||
         (path[0] === "'" && path[path.length - 1] !== "'") ||
         (path[0] !== "'" && path[0] !== '"')
       ) {
         throw new Error('`@source` paths must be quoted.')
       }
-      globs.push({ base: context.base as string, pattern: path.slice(1, -1) })
+
+      let source = path.slice(1, -1)
+
+      if (enableSourceInline && inline) {
+        let destination = not ? ignoredCandidates : inlineCandidates
+        let sources = segment(source, ' ')
+        for (let source of sources) {
+          for (let candidate of expand(source)) {
+            destination.push(candidate)
+          }
+        }
+      } else {
+        globs.push({ base: context.base as string, pattern: source })
+      }
       replaceWith([])
       return
     }
@@ -505,6 +537,12 @@ async function parseCss(
     designSystem.important = important
   }
 
+  if (ignoredCandidates.length > 0) {
+    for (let candidate of ignoredCandidates) {
+      designSystem.invalidCandidates.add(candidate)
+    }
+  }
+
   // Apply hooks from backwards compatibility layer. This function takes a lot
   // of random arguments because it really just needs access to "the world" to
   // do whatever ungodly things it needs to do to make things backwards
@@ -603,6 +641,7 @@ async function parseCss(
     root,
     utilitiesNode,
     features,
+    inlineCandidates,
   }
 }
 
@@ -615,7 +654,8 @@ export async function compileAst(
   features: Features
   build(candidates: string[]): AstNode[]
 }> {
-  let { designSystem, ast, globs, root, utilitiesNode, features } = await parseCss(input, opts)
+  let { designSystem, ast, globs, root, utilitiesNode, features, inlineCandidates } =
+    await parseCss(input, opts)
 
   if (process.env.NODE_ENV !== 'test') {
     ast.unshift(comment(`! tailwindcss v${version} | MIT License | https://tailwindcss.com `))
@@ -632,6 +672,14 @@ export async function compileAst(
   let allValidCandidates = new Set<string>()
   let compiled = null as AstNode[] | null
   let previousAstNodeCount = 0
+  let defaultDidChange = false
+
+  for (let candidate of inlineCandidates) {
+    if (!designSystem.invalidCandidates.has(candidate)) {
+      allValidCandidates.add(candidate)
+      defaultDidChange = true
+    }
+  }
 
   return {
     globs,
@@ -647,7 +695,8 @@ export async function compileAst(
         return compiled
       }
 
-      let didChange = false
+      let didChange = defaultDidChange
+      defaultDidChange = false
 
       // Add all new candidates unless we know that they are invalid.
       let prevSize = allValidCandidates.size
diff --git a/packages/tailwindcss/src/utils/brace-expansion.bench.ts b/packages/tailwindcss/src/utils/brace-expansion.bench.ts
@@ -0,0 +1,14 @@
+// import braces from 'braces'
+import { bench } from 'vitest'
+import { expand } from './brace-expansion'
+
+const PATTERN =
+  '{{xs,sm,md,lg}:,}{border-{x,y,t,r,b,l,s,e},bg,text,cursor,accent}-{{red,orange,amber,yellow,lime,green,emerald,teal,cyan,sky,blue,indigo,violet,purple,fuchsia,pink,rose,slate,gray,zinc,neutral,stone}-{50,{100..900..100},950},black,white}{,/{0..100}}'
+
+// bench('braces', () => {
+//   void braces.expand(PATTERN)
+// })
+
+bench('./brace-expansion', () => {
+  void expand(PATTERN)
+})
diff --git a/packages/tailwindcss/src/utils/brace-expansion.test.ts b/packages/tailwindcss/src/utils/brace-expansion.test.ts
diff --git a/packages/tailwindcss/src/utils/brace-expansion.ts b/packages/tailwindcss/src/utils/brace-expansion.ts
