Add support for prefixes (tailwindlabs#14501)

This PR adds support for requiring a custom prefix on utility classes.

Prefixes work a bit differently in v4 than they did in v3:
- They look like a custom variant: `tw:bg-white`
- It is always first in a utility — even before other variants:
`tw:hover:bg-white`
- It is required on **all** utility classes — even arbitrary properties:
`tw:[color:red]`
- Prefixes also apply to generated CSS variables which will be separated
by a dash: `--tw-color-white: #fff;`
- Only alpha (a-z) characters are allowed in a prefix — so no `#tw#` or
`__` or similar prefixes are allowed

To configure a prefix you can use add `prefix(tw)` to your theme or when
importing Tailwind CSS like so:

```css
/* when importing `tailwindcss` */
@import 'tailwindcss' prefix(tw);

/* when importing the theme separately */
@import 'tailwindcss/theme' prefix(tw);

/* or when using an entirely custom theme */
@theme prefix(tw) {
  --color-white: #fff;
  --breakpoint-sm: 640px;
  /* … */
}
```

This will configure Tailwind CSS to require a prefix on all utility
classes when used in HTML:

```html
<div class="tw:bg-white tw:p-4">
  This will have a white background and 4 units of padding.
</div>

<div class="bg-white p-4">
  This will not because the prefix is missing.
</div>
```

and when used in CSS via `@apply`:
```css
.my-class {
  @apply tw:bg-white tw:p-4;
}
```

Additionally, the prefix will be added to the generated CSS variables.
You **do not** need to prefix the variables in the `@theme` block
yourself — Tailwind CSS handles this automatically.

```css
:root {
  --tw-color-white: #fff;
  --tw-breakpoint-sm: 640px;
}
```

A prefix is not necessary when using the `theme(…)` function in your CSS
or JS given that plugins will not know what the current prefix is and
must work with or without a prefix:

```css
.my-class {
  color: theme(--color-white);
}
```

However, because the variables themselves are prefixed when outputting
the CSS, you **do** need to prefix the variables when using `var(…)` in
your CSS:

```css
.my-class {
  color: var(--tw-color-white);
}
```

If you want to customize the prefix itself change `tw` to something
else:

```css
/* my:underline, my:hover:bg-red-500, etc… */
@import 'tailwindcss' prefix(my);
```

---------

Co-authored-by: Philipp Spiess <hello@philippspiess.com>

Author: thecrypticace

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add support for prefixes ([#14501](https://github.com/tailwindlabs/tailwindcss/pull/14501))
+
 ### Fixed
 
 - _Experimental_: Improve codemod output, keep CSS after last Tailwind directive unlayered ([#14512](https://github.com/tailwindlabs/tailwindcss/pull/14512))

packages/tailwindcss/src/candidate.test.ts

@@ -6,12 +6,17 @@ import { Variants } from './variants'
 
 function run(
   candidate: string,
-  { utilities, variants }: { utilities?: Utilities; variants?: Variants } = {},
+  {
+    utilities,
+    variants,
+    prefix,
+  }: { utilities?: Utilities; variants?: Variants; prefix?: string } = {},
 ) {
   utilities ??= new Utilities()
   variants ??= new Variants()
 
   let designSystem = buildDesignSystem(new Theme())
+  designSystem.theme.prefix = prefix ?? null
 
   designSystem.utilities = utilities
   designSystem.variants = variants
@@ -1259,3 +1264,46 @@ it('should parse a variant containing an arbitrary string with unbalanced parens
     ]
   `)
 })
+
+it('should parse candidates with a prefix', () => {
+  let utilities = new Utilities()
+  utilities.static('flex', () => [])
+
+  let variants = new Variants()
+  variants.static('hover', () => {})
+
+  // A prefix is required
+  expect(run(`flex`, { utilities, variants, prefix: 'tw' })).toEqual([])
+
+  // The prefix always comes first — even before variants
+  expect(run(`tw:flex`, { utilities, variants, prefix: 'tw' })).toMatchInlineSnapshot(`
+    [
+      {
+        "important": false,
+        "kind": "static",
+        "negative": false,
+        "raw": "tw:flex",
+        "root": "flex",
+        "variants": [],
+      },
+    ]
+  `)
+  expect(run(`tw:hover:flex`, { utilities, variants, prefix: 'tw' })).toMatchInlineSnapshot(`
+    [
+      {
+        "important": false,
+        "kind": "static",
+        "negative": false,
+        "raw": "tw:hover:flex",
+        "root": "flex",
+        "variants": [
+          {
+            "compounds": true,
+            "kind": "static",
+            "root": "hover",
+          },
+        ],
+      },
+    ]
+  `)
+})

packages/tailwindcss/src/candidate.ts

@@ -226,6 +226,15 @@ export function* parseCandidate(input: string, designSystem: DesignSystem): Iter
   //             ^^^^^^^^^  -> Base
   let rawVariants = segment(input, ':')
 
+  // A prefix is a special variant used to prefix all utilities. When present,
+  // all utilities must start with that variant which we will then remove from
+  // the variant list so no other part of the codebase has to know about it.
+  if (designSystem.theme.prefix) {
+    if (rawVariants[0] !== designSystem.theme.prefix) return null
+
+    rawVariants.shift()
+  }
+
   // Safety: At this point it is safe to use TypeScript's non-null assertion
   // operator because even if the `input` was an empty string, splitting an
   // empty string by `:` will always result in an array with at least one

packages/tailwindcss/src/compat/apply-compat-hooks.ts

@@ -13,6 +13,8 @@ import { buildPluginApi, type CssPluginOptions, type Plugin } from './plugin-api
 import { registerScreensConfig } from './screens-config'
 import { registerThemeVariantOverrides } from './theme-variants'
 
+const IS_VALID_PREFIX = /^[a-z]+$/
+
 export async function applyCompatibilityHooks({
   designSystem,
   base,
@@ -208,6 +210,25 @@ export async function applyCompatibilityHooks({
   registerThemeVariantOverrides(resolvedUserConfig, designSystem)
   registerScreensConfig(resolvedUserConfig, designSystem)
 
+  // If a prefix has already been set in CSS don't override it
+  if (!designSystem.theme.prefix && resolvedConfig.prefix) {
+    if (resolvedConfig.prefix.endsWith('-')) {
+      resolvedConfig.prefix = resolvedConfig.prefix.slice(0, -1)
+
+      console.warn(
+        `The prefix "${resolvedConfig.prefix}" is invalid. Prefixes must be lowercase ASCII letters (a-z) only and is written as a variant before all utilities. We have fixed up the prefix for you. Remove the trailing \`-\` to silence this warning.`,
+      )
+    }
+
+    if (!IS_VALID_PREFIX.test(resolvedConfig.prefix)) {
+      throw new Error(
+        `The prefix "${resolvedConfig.prefix}" is invalid. Prefixes must be lowercase ASCII letters (a-z) only.`,
+      )
+    }
+
+    designSystem.theme.prefix = resolvedConfig.prefix
+  }
+
   // Replace `resolveThemeValue` with a version that is backwards compatible
   // with dot-notation but also aware of any JS theme configurations registered
   // by plugins or JS config files. This is significantly slower than just

packages/tailwindcss/src/compat/config.test.ts

@@ -1217,3 +1217,157 @@ test('merges css breakpoints with js config screens', async () => {
       "
     `)
 })
+
+test('utilities must be prefixed', async () => {
+  let input = css`
+    @tailwind utilities;
+    @config "./config.js";
+
+    @utility custom {
+      color: red;
+    }
+  `
+
+  let compiler = await compile(input, {
+    loadModule: async (id, base) => ({
+      base,
+      module: { prefix: 'tw' },
+    }),
+  })
+
+  // Prefixed utilities are generated
+  expect(compiler.build(['tw:underline', 'tw:hover:line-through', 'tw:custom']))
+    .toMatchInlineSnapshot(`
+    ".tw\\:custom {
+      color: red;
+    }
+    .tw\\:underline {
+      text-decoration-line: underline;
+    }
+    .tw\\:hover\\:line-through {
+      &:hover {
+        @media (hover: hover) {
+          text-decoration-line: line-through;
+        }
+      }
+    }
+    "
+  `)
+
+  // Non-prefixed utilities are ignored
+  compiler = await compile(input, {
+    loadModule: async (id, base) => ({
+      base,
+      module: { prefix: 'tw' },
+    }),
+  })
+
+  expect(compiler.build(['underline', 'hover:line-through', 'custom'])).toEqual('')
+})
+
+test('utilities used in @apply must be prefixed', async () => {
+  let compiler = await compile(
+    css`
+      @config "./config.js";
+
+      .my-underline {
+        @apply tw:underline;
+      }
+    `,
+    {
+      loadModule: async (id, base) => ({
+        base,
+        module: { prefix: 'tw' },
+      }),
+    },
+  )
+
+  // Prefixed utilities are generated
+  expect(compiler.build([])).toMatchInlineSnapshot(`
+    ".my-underline {
+      text-decoration-line: underline;
+    }
+    "
+  `)
+
+  // Non-prefixed utilities cause an error
+  expect(() =>
+    compile(
+      css`
+        @config "./config.js";
+
+        .my-underline {
+          @apply underline;
+        }
+      `,
+      {
+        loadModule: async (id, base) => ({
+          base,
+          module: { prefix: 'tw' },
+        }),
+      },
+    ),
+  ).rejects.toThrowErrorMatchingInlineSnapshot(
+    `[Error: Cannot apply unknown utility class: underline]`,
+  )
+})
+
+test('Prefixes configured in CSS take precedence over those defined in JS configs', async () => {
+  let compiler = await compile(
+    css`
+      @theme prefix(wat) {
+        --color-red: #f00;
+        --color-green: #0f0;
+        --breakpoint-sm: 640px;
+      }
+
+      @config "./plugin.js";
+
+      @tailwind utilities;
+
+      @utility custom {
+        color: red;
+      }
+    `,
+    {
+      async loadModule(id, base) {
+        return {
+          base,
+          module: { prefix: 'tw' },
+        }
+      },
+    },
+  )
+
+  expect(compiler.build(['wat:custom'])).toMatchInlineSnapshot(`
+    ":root {
+      --wat-color-red: #f00;
+      --wat-color-green: #0f0;
+      --wat-breakpoint-sm: 640px;
+    }
+    .wat\\:custom {
+      color: red;
+    }
+    "
+  `)
+})
+
+test('a prefix must be letters only', async () => {
+  await expect(() =>
+    compile(
+      css`
+        @config "./plugin.js";
+      `,
+      {
+        async loadModule(id, base) {
+          return {
+            base,
+            module: { prefix: '__' },
+          }
+        },
+      },
+    ),
+  ).rejects.toThrowErrorMatchingInlineSnapshot(
+    `[Error: The prefix "__" is invalid. Prefixes must be lowercase ASCII letters (a-z) only.]`,
+  )
+})

packages/tailwindcss/src/compat/config/resolve-config.ts

@@ -27,6 +27,7 @@ interface ResolutionContext {
 }
 
 let minimal: ResolvedConfig = {
+  prefix: '',
   darkMode: null,
   theme: {},
   plugins: [],
@@ -54,11 +55,15 @@ export function resolveConfig(design: DesignSystem, files: ConfigFile[]): Resolv
     extractConfigs(ctx, file)
   }
 
-  // Merge dark mode
+  // Merge top level keys
   for (let config of ctx.configs) {
     if ('darkMode' in config && config.darkMode !== undefined) {
       ctx.result.darkMode = config.darkMode ?? null
     }
+
+    if ('prefix' in config && config.prefix !== undefined) {
+      ctx.result.prefix = config.prefix ?? ''
+    }
   }
 
   // Merge themes

packages/tailwindcss/src/compat/config/types.ts

@@ -69,3 +69,12 @@ export interface UserConfig {
 export interface ResolvedConfig {
   darkMode: DarkModeStrategy | null
 }
+
+// `prefix` support
+export interface UserConfig {
+  prefix?: string
+}
+
+export interface ResolvedConfig {
+  prefix: string
+}