Template migrations: Migrate v3 prefixes to v4 (#14557)

This PR adds a new migration that can migrate Tailwind CSS v3 style
prefixes into Tailwind CSS v4.

The migration is split into three separate pieces of work:

1. Firstly, we need to read the full JavaScript config to get the _old_
prefix option. This is necessary because in v4, we will not allow things
like custom-separators for the prefix. From this option we will then try
and compute a new prefix (in 90% of the cases this is going to just
remove the trailing `-` but it can also work in more complex cases).
2. Then we migrate all Candidates. The important thing here is that we
need to operate on the raw candidate string because by relying on
`parseCandidate` (which we do for all other migrations) would not work,
as the candidates are not valid in v4 syntax. More on that in a bit.
3. Lastly we also make sure to update the CSS config to include the new
prefix. This is done by prepending the prefix option like so:
    
    ```css
    @import "tailwindcss" prefix(tw);
    ```

### Migrating candidates

The main difference between v3 prefixes and v4 prefixes is that in v3,
the prefix was _part of the utility_ where as in v4 it is _always in
front of the CSS class.

So, for example, this candidate in v3: 

```
hover:-tw-mr-4
```

Would be converted to the following in v4:

```
tw:hover:-mr-4
```

Since the first example _won't parse as a valid Candidate in v4, as the
`tw-mr` utility does not exist, we have to operate on the raw candidate
string first. To do this I created a fork of the `parseCandidate`
function _without any validation of utilities or variants_. This is used
to identify part of the candidate that is the `base` and then ensuring
the `base` starts with the old prefix. We then remove this to create an
"unprefixed" candidate that we validate against a version of the
DesignSystem _with no prefixes configured_. If the variant is valid this
way, we can then print it again with the `DesignSystem` that has the new
prefix to get the migrated version.

Since we set up the `DesignSystem` to include the new prefix, we can
also be certain that migrations that happen afterwards would still
disqualify candidates that aren't valid according to the new prefix
policy. This does mean we need to have the prefix fixup be the first
step in our pipeline.

One interesting bit is that in v3, arbitrary properties did not require
prefixes where as in v4 they do. So the following candidate:

```
[color:red]
```

Will be converted to:

```
tw:[color:red]
```

Author: philipp-spiess

CHANGELOG.md

@@ -13,8 +13,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Expose timing information in debug mode ([#14553](https://github.com/tailwindlabs/tailwindcss/pull/14553))
 - Add support for `blocklist` in config files ([#14556](https://github.com/tailwindlabs/tailwindcss/pull/14556))
 - _Experimental_: Migrate `@import "tailwindcss/tailwind.css"` to `@import "tailwindcss"` ([#14514](https://github.com/tailwindlabs/tailwindcss/pull/14514))
-- _Experimental_: Add template codemods for removal of automatic `var(…)` injection ([#14526](https://github.com/tailwindlabs/tailwindcss/pull/14526))
 - _Experimental_: Add template codemods for migrating `bg-gradient-*` utilities to `bg-linear-*` ([#14537](https://github.com/tailwindlabs/tailwindcss/pull/14537]))
+- _Experimental_: Add template codemods for migrating prefixes ([#14557](https://github.com/tailwindlabs/tailwindcss/pull/14557]))
+- _Experimental_: Add template codemods for removal of automatic `var(…)` injection ([#14526](https://github.com/tailwindlabs/tailwindcss/pull/14526))
 - _Experimental_: Add template codemods for migrating important utilities (e.g. `!flex` to `flex!`) ([#14502](https://github.com/tailwindlabs/tailwindcss/pull/14502))
 
 ### Fixed

integrations/upgrade/index.test.ts

@@ -43,6 +43,50 @@ test(
   },
 )
 
+test(
+  `upgrades a v3 project with prefixes to v4`,
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "@tailwindcss/upgrade": "workspace:^"
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+          prefix: 'tw__',
+        }
+      `,
+      'src/index.html': html`
+        <h1>🤠👋</h1>
+        <div class="!tw__flex sm:!tw__block tw__bg-gradient-to-t flex [color:red]"></div>
+      `,
+      'src/input.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ exec, fs }) => {
+    await exec('npx @tailwindcss/upgrade -c tailwind.config.js')
+
+    await fs.expectFileToContain(
+      'src/index.html',
+      html`
+        <h1>🤠👋</h1>
+        <div class="tw:flex! tw:sm:block! tw:bg-linear-to-t flex tw:[color:red]"></div>
+      `,
+    )
+
+    await fs.expectFileToContain('src/input.css', css`@import 'tailwindcss' prefix(tw);`)
+  },
+)
+
 test(
   'migrate @apply',
   {

packages/@tailwindcss-node/src/compile.ts

@@ -37,7 +37,7 @@ export async function __unstable__loadDesignSystem(css: string, { base }: { base
   })
 }
 
-async function loadModule(id: string, base: string, onDependency: (path: string) => void) {
+export async function loadModule(id: string, base: string, onDependency: (path: string) => void) {
   if (id[0] !== '.') {
     let resolvedPath = await resolveJsId(id, base)
     if (!resolvedPath) {

packages/@tailwindcss-node/src/index.ts

@@ -1,7 +1,7 @@
 import * as Module from 'node:module'
 import { pathToFileURL } from 'node:url'
 import * as env from './env'
-export * from './compile'
+export { __unstable__loadDesignSystem, compile } from './compile'
 export * from './normalize-path'
 export { env }
 

packages/@tailwindcss-upgrade/package.json

@@ -31,6 +31,7 @@
     "@tailwindcss/oxide": "workspace:^",
     "enhanced-resolve": "^5.17.1",
     "globby": "^14.0.2",
+    "jiti": "^2.0.0-beta.3",
     "mri": "^1.2.0",
     "picocolors": "^1.0.1",
     "postcss": "^8.4.41",

packages/@tailwindcss-upgrade/src/codemods/migrate-tailwind-directives.test.ts

@@ -6,9 +6,9 @@ import { migrateTailwindDirectives } from './migrate-tailwind-directives'
 
 const css = dedent
 
-function migrate(input: string) {
+function migrate(input: string, options: { newPrefix?: string } = {}) {
   return postcss()
-    .use(migrateTailwindDirectives())
+    .use(migrateTailwindDirectives(options))
     .use(formatNodes())
     .process(input, { from: expect.getState().testPath })
     .then((result) => result.css)
@@ -24,6 +24,21 @@ it("should not migrate `@import 'tailwindcss'`", async () => {
   `)
 })
 
+it("should append a prefix to `@import 'tailwindcss'`", async () => {
+  expect(
+    await migrate(
+      css`
+        @import 'tailwindcss';
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss' prefix(tw);
+  `)
+})
+
 it('should migrate the tailwind.css import', async () => {
   expect(
     await migrate(css`
@@ -34,6 +49,21 @@ it('should migrate the tailwind.css import', async () => {
   `)
 })
 
+it('should migrate the tailwind.css import with a prefix', async () => {
+  expect(
+    await migrate(
+      css`
+        @import 'tailwindcss/tailwind.css';
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss' prefix(tw);
+  `)
+})
+
 it('should migrate the default @tailwind directives to a single import', async () => {
   expect(
     await migrate(css`
@@ -46,6 +76,23 @@ it('should migrate the default @tailwind directives to a single import', async (
   `)
 })
 
+it('should migrate the default @tailwind directives to a single import with a prefix', async () => {
+  expect(
+    await migrate(
+      css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss' prefix(tw);
+  `)
+})
+
 it('should migrate the default @tailwind directives as imports to a single import', async () => {
   expect(
     await migrate(css`
@@ -64,7 +111,7 @@ it('should migrate the default @tailwind directives to a single import in a vali
       @charset "UTF-8";
       @layer foo, bar, baz;
 
-      /**! 
+      /**!
        * License header
        */
 
@@ -84,7 +131,7 @@ it('should migrate the default @tailwind directives to a single import in a vali
       @charset "UTF-8";
       @layer foo, bar, baz;
 
-      /**! 
+      /**!
        * License header
        */
 
@@ -102,7 +149,7 @@ it('should migrate the default @tailwind directives as imports to a single impor
       @charset "UTF-8";
       @layer foo, bar, baz;
 
-      /**! 
+      /**!
        * License header
        */
 
@@ -114,14 +161,31 @@ it('should migrate the default @tailwind directives as imports to a single impor
     @charset "UTF-8";
     @layer foo, bar, baz;
 
-    /**! 
+    /**!
      * License header
      */
 
     @import 'tailwindcss';
   `)
 })
 
+it('should migrate the default @tailwind directives as imports to a single import with a prefix', async () => {
+  expect(
+    await migrate(
+      css`
+        @import 'tailwindcss/base';
+        @import 'tailwindcss/components';
+        @import 'tailwindcss/utilities';
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss' prefix(tw);
+  `)
+})
+
 it.each([
   [
     // The default order
@@ -213,6 +277,22 @@ it('should migrate `@tailwind base` to theme and preflight imports', async () =>
   `)
 })
 
+it('should migrate `@tailwind base` to theme and preflight imports with a prefix', async () => {
+  expect(
+    await migrate(
+      css`
+        @tailwind base;
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss/theme' layer(theme) prefix(tw);
+    @import 'tailwindcss/preflight' layer(base);
+  `)
+})
+
 it('should migrate `@import "tailwindcss/base"` to theme and preflight imports', async () => {
   expect(
     await migrate(css`
@@ -224,6 +304,22 @@ it('should migrate `@import "tailwindcss/base"` to theme and preflight imports',
   `)
 })
 
+it('should migrate `@import "tailwindcss/base"` to theme and preflight imports with a prefix', async () => {
+  expect(
+    await migrate(
+      css`
+        @import 'tailwindcss/base';
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss/theme' layer(theme) prefix(tw);
+    @import 'tailwindcss/preflight' layer(base);
+  `)
+})
+
 it('should migrate `@tailwind utilities` to an import', async () => {
   expect(
     await migrate(css`
@@ -273,6 +369,22 @@ it('should migrate `@tailwind base` and `@tailwind utilities` to a single import
   `)
 })
 
+it('should migrate `@tailwind base` and `@tailwind utilities` to a single import with a prefix', async () => {
+  expect(
+    await migrate(
+      css`
+        @import 'tailwindcss/base';
+        @import 'tailwindcss/utilities';
+      `,
+      {
+        newPrefix: 'tw',
+      },
+    ),
+  ).toEqual(css`
+    @import 'tailwindcss' prefix(tw);
+  `)
+})
+
 it('should drop `@tailwind screens;`', async () => {
   expect(
     await migrate(css`

packages/@tailwindcss-upgrade/src/codemods/migrate-tailwind-directives.ts

@@ -2,7 +2,9 @@ import { AtRule, type ChildNode, type Plugin, type Root } from 'postcss'
 
 const DEFAULT_LAYER_ORDER = ['theme', 'base', 'components', 'utilities']
 
-export function migrateTailwindDirectives(): Plugin {
+export function migrateTailwindDirectives(options: { newPrefix?: string }): Plugin {
+  let prefixParams = options.newPrefix ? ` prefix(${options.newPrefix})` : ''
+
   function migrate(root: Root) {
     let baseNode = null as AtRule | null
     let utilitiesNode = null as AtRule | null
@@ -21,6 +23,11 @@ export function migrateTailwindDirectives(): Plugin {
         node.params = node.params.replace('tailwindcss/tailwind.css', 'tailwindcss')
       }
 
+      // Append any new prefix() param to existing `@import 'tailwindcss'` directives
+      if (node.name === 'import' && node.params.match(/^["']tailwindcss["']/)) {
+        node.params += prefixParams
+      }
+
       // Track old imports and directives
       else if (
         (node.name === 'tailwind' && node.params === 'base') ||
@@ -52,7 +59,9 @@ export function migrateTailwindDirectives(): Plugin {
     // Insert default import if all directives are present
     if (baseNode !== null && utilitiesNode !== null) {
       if (!defaultImportNode) {
-        findTargetNode(orderedNodes).before(new AtRule({ name: 'import', params: "'tailwindcss'" }))
+        findTargetNode(orderedNodes).before(
+          new AtRule({ name: 'import', params: `'tailwindcss'${prefixParams}` }),
+        )
       }
       baseNode?.remove()
       utilitiesNode?.remove()
@@ -69,7 +78,7 @@ export function migrateTailwindDirectives(): Plugin {
     } else if (baseNode !== null) {
       if (!themeImportNode) {
         findTargetNode(orderedNodes).before(
-          new AtRule({ name: 'import', params: "'tailwindcss/theme' layer(theme)" }),
+          new AtRule({ name: 'import', params: `'tailwindcss/theme' layer(theme)${prefixParams}` }),
         )
       }