Template migrations: Add automatic var injection codemods

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add support for prefixes ([#14501](https://github.com/tailwindlabs/tailwindcss/pull/14501))
+- _Experimental_: Add template codemods for removal of automatic `var(…)` injection ([#14526](https://github.com/tailwindlabs/tailwindcss/pull/14526))
 
 ### Fixed
 

integrations/upgrade/index.test.ts

@@ -19,7 +19,7 @@ test(
       `,
       'src/index.html': html`
         <h1>🤠👋</h1>
-        <div class="!flex sm:!block"></div>
+        <div class="!flex sm:!block bg-[--my-red]"></div>
       `,
       'src/input.css': css`
         @tailwind base;
@@ -35,7 +35,7 @@ test(
       'src/index.html',
       html`
         <h1>🤠👋</h1>
-        <div class="flex! sm:block!"></div>
+        <div class="flex! sm:block! bg-[var(--my-red)]"></div>
       `,
     )
 

packages/@tailwindcss-upgrade/src/template/codemods/automatic-var-injection.test.ts

@@ -0,0 +1,43 @@
+import { __unstable__loadDesignSystem } from '@tailwindcss/node'
+import { expect, test } from 'vitest'
+import { printCandidate } from '../candidates'
+import { automaticVarInjection } from './automatic-var-injection'
+
+test.each([
+  // Arbitrary candidates
+  ['[color:--my-color]', '[color:var(--my-color)]'],
+
+  // Arbitrary values for functional candidates
+  ['bg-[--my-color]', 'bg-[var(--my-color)]'],
+  ['bg-[color:--my-color]', 'bg-[color:var(--my-color)]'],
+  ['border-[length:--my-length]', 'border-[length:var(--my-length)]'],
+  ['border-[line-width:--my-width]', 'border-[line-width:var(--my-width)]'],
+
+  // Does not add var() if there is a _ before the variable name
+  ['bg-[_--my-color]', null],
+  ['bg-[color:_--my-color]', null],
+  ['border-[length:_--my-length]', null],
+  ['border-[line-width:_--my-width]', null],
+
+  // Modifiers
+  ['[color:--my-color]/[--my-opacity]', '[color:var(--my-color)]/[var(--my-opacity)]'],
+  ['bg-red-500/[--my-opacity]', 'bg-red-500/[var(--my-opacity)]'],
+  ['bg-[--my-color]/[--my-opacity]', 'bg-[var(--my-color)]/[var(--my-opacity)]'],
+  ['bg-[color:--my-color]/[--my-opacity]', 'bg-[color:var(--my-color)]/[var(--my-opacity)]'],
+
+  ['[color:--my-color]/[_--my-opacity]', '[color:var(--my-color)]/[_--my-opacity]'],
+  ['bg-red-500/[_--my-opacity]', null],
+  ['bg-[--my-color]/[_--my-opacity]', 'bg-[var(--my-color)]/[_--my-opacity]'],
+  ['bg-[color:--my-color]/[_--my-opacity]', 'bg-[color:var(--my-color)]/[_--my-opacity]'],
+
+  // Variants
+  ['supports-[--test]:flex', 'supports-[var(--test)]:flex'],
+  ['supports-[_--test]:flex', null],
+])('%s => %s', async (candidate, result) => {
+  let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
+    base: __dirname,
+  })
+
+  let migrated = automaticVarInjection(designSystem.parseCandidate(candidate)[0]!)
+  expect(migrated ? printCandidate(migrated) : migrated).toEqual(result)
+})

packages/@tailwindcss-upgrade/src/template/codemods/automatic-var-injection.ts

@@ -0,0 +1,75 @@
+import type { Candidate, Variant } from '../../../../tailwindcss/src/candidate'
+
+export function automaticVarInjection(candidate: Candidate): Candidate | null {
+  let didChange = false
+
+  // Add `var(…)` in modifier position, e.g.:
+  //
+  // `bg-red-500/[--my-opacity]` => `bg-red-500/[var(--my-opacity)]`
+  if (
+    'modifier' in candidate &&
+    candidate.modifier?.kind === 'arbitrary' &&
+    candidate.modifier.value.startsWith('--')
+  ) {
+    candidate.modifier.value = `var(${candidate.modifier.value})`
+    didChange = true
+  }
+
+  // Add `var(…)` to all variants, e.g.:
+  //
+  // `supports-[--test]:flex'` => `supports-[var(--test)]:flex`
+  for (let variant of candidate.variants) {
+    let didChangeVariant = injectVarIntoVariant(variant)
+    if (didChangeVariant) {
+      didChange = true
+    }
+  }
+
+  // Add `var(…)` to arbitrary candidates, e.g.:
+  //
+  // `[color:--my-color]` => `[color:var(--my-color)]`
+  if (candidate.kind === 'arbitrary' && candidate.value.startsWith('--')) {
+    candidate.value = `var(${candidate.value})`
+    didChange = true
+  }
+
+  // Add `var(…)` to arbitrary values for functional candidates, e.g.:
+  //
+  // `bg-[--my-color]` => `bg-[var(--my-color)]`
+  if (
+    candidate.kind === 'functional' &&
+    candidate.value &&
+    candidate.value.kind === 'arbitrary' &&
+    candidate.value.value.startsWith('--')
+  ) {
+    candidate.value.value = `var(${candidate.value.value})`
+    didChange = true
+  }
+
+  if (didChange) {
+    return candidate
+  }
+  return null
+}
+
+function injectVarIntoVariant(variant: Variant): boolean {
+  let didChange = false
+  if (
+    variant.kind === 'functional' &&
+    variant.value &&
+    variant.value.kind === 'arbitrary' &&
+    variant.value.value.startsWith('--')
+  ) {
+    variant.value.value = `var(${variant.value.value})`
+    didChange = true
+  }
+
+  if (variant.kind === 'compound') {
+    let compoundDidChange = injectVarIntoVariant(variant.variant)
+    if (compoundDidChange) {
+      didChange = true
+    }
+  }
+
+  return didChange
+}

packages/@tailwindcss-upgrade/src/template/migrate.ts

@@ -3,14 +3,15 @@ import path from 'node:path'
 import type { Candidate } from '../../../tailwindcss/src/candidate'
 import type { DesignSystem } from '../../../tailwindcss/src/design-system'
 import { extractCandidates, printCandidate, replaceCandidateInContent } from './candidates'
+import { automaticVarInjection } from './codemods/automatic-var-injection'
 import { migrateImportant } from './codemods/migrate-important'
 
 export type Migration = (candidate: Candidate) => Candidate | null
 
 export default async function migrateContents(
   designSystem: DesignSystem,
   contents: string,
-  migrations: Migration[] = [migrateImportant],
+  migrations: Migration[] = [migrateImportant, automaticVarInjection],
 ): Promise<string> {
   let candidates = await extractCandidates(designSystem, contents)