Migrate simple PostCSS setup (#14612)

This PR attempts to detect simple postcss setups: These are setups that
do not load dynamic modules and are based off the examples we are
[recommending in our
docs](https://tailwindcss.com/docs/installation/using-postcss). We
detect wether a config is appropriate by having it use the object plugin
config and by not requiring any other modules:

```js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}
```

When we find such a config file, we will go over it line-by-line and
attempt to:

- Upgrade `tailwindcss:` to `'@tailwindcss/postcss':`
- Remove `autoprefixer` if used

We then attempt to install and remove the respective npm packages based
on the package manger we detect.

And since we now have logic to upgrade packages, this also makes sure to
install `tailwindcss@next` at the end of a sucessful migration.

---------

Co-authored-by: Robin Malfait <[email protected]>

Author: philipp-spiess

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add support for `tailwindcss/colors.js`, `tailwindcss/defaultTheme.js`, and `tailwindcss/plugin.js` exports ([#14595](https://github.com/tailwindlabs/tailwindcss/pull/14595))
 - Support `keyframes` in JS config file themes ([#14594](https://github.com/tailwindlabs/tailwindcss/pull/14594))
+- _Upgrade (experimental)_: Migrate v3 PostCSS setups to v4 in some cases ([#14612](https://github.com/tailwindlabs/tailwindcss/pull/14612))
 - _Upgrade (experimental)_: The upgrade tool now automatically discovers your JavaScript config ([#14597](https://github.com/tailwindlabs/tailwindcss/pull/14597))
 
 ### Fixed

integrations/upgrade/index.test.ts

@@ -1,3 +1,4 @@
+import { expect } from 'vitest'
 import { css, html, js, json, test } from '../utils'
 
 test(
@@ -40,6 +41,12 @@ test(
     )
 
     await fs.expectFileToContain('src/input.css', css`@import 'tailwindcss';`)
+
+    let packageJsonContent = await fs.read('package.json')
+    let packageJson = JSON.parse(packageJsonContent)
+    expect(packageJson.dependencies).toMatchObject({
+      tailwindcss: expect.stringContaining('4.0.0'),
+    })
   },
 )
 
@@ -265,6 +272,233 @@ test(
   },
 )
 
+test(
+  'migrates a simple postcss setup',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "postcss": "^8",
+            "postcss-cli": "^10",
+            "postcss-import": "^16",
+            "autoprefixer": "^10",
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'postcss.config.js': js`
+        module.exports = {
+          plugins: {
+            'postcss-import': {},
+            'tailwindcss/nesting': 'postcss-nesting',
+            tailwindcss: {},
+            autoprefixer: {},
+          },
+        }
+      `,
+      'src/index.html': html`
+        <div class="bg-[--my-red]"></div>
+      `,
+      'src/index.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ fs, exec }) => {
+    await exec('npx @tailwindcss/upgrade')
+
+    await fs.expectFileToContain(
+      'postcss.config.js',
+      js`
+        module.exports = {
+          plugins: {
+            '@tailwindcss/postcss': {},
+          },
+        }
+      `,
+    )
+    await fs.expectFileToContain('src/index.css', css`@import 'tailwindcss';`)
+    await fs.expectFileToContain(
+      'src/index.html',
+      // prettier-ignore
+      js`
+        <div class="bg-[var(--my-red)]"></div>
+      `,
+    )
+
+    let packageJsonContent = await fs.read('package.json')
+    let packageJson = JSON.parse(packageJsonContent)
+    expect(packageJson.dependencies).toMatchObject({
+      tailwindcss: expect.stringContaining('4.0.0'),
+    })
+    expect(packageJson.dependencies).not.toHaveProperty('autoprefixer')
+    expect(packageJson.dependencies).not.toHaveProperty('postcss-import')
+    expect(packageJson.devDependencies).toMatchObject({
+      '@tailwindcss/postcss': expect.stringContaining('4.0.0'),
+    })
+  },
+)
+
+test(
+  'migrates a postcss setup using package.json config',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "postcss": "^8",
+            "postcss-cli": "^10",
+            "postcss-import": "^16",
+            "autoprefixer": "^10",
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          },
+          "postcss": {
+            "plugins": {
+              "postcss-import": {},
+              "tailwindcss/nesting": "postcss-nesting",
+              "tailwindcss": {},
+              "autoprefixer": {}
+            }
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'src/index.html': html`
+        <div class="bg-[--my-red]"></div>
+      `,
+      'src/index.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ fs, exec }) => {
+    await exec('npx @tailwindcss/upgrade')
+
+    await fs.expectFileToContain('src/index.css', css`@import 'tailwindcss';`)
+    await fs.expectFileToContain(
+      'src/index.html',
+      // prettier-ignore
+      js`
+        <div class="bg-[var(--my-red)]"></div>
+      `,
+    )
+
+    let packageJsonContent = await fs.read('package.json')
+    let packageJson = JSON.parse(packageJsonContent)
+    expect(packageJson.postcss).toMatchInlineSnapshot(`
+      {
+        "plugins": {
+          "@tailwindcss/postcss": {},
+        },
+      }
+    `)
+
+    expect(packageJson.dependencies).toMatchObject({
+      tailwindcss: expect.stringContaining('4.0.0'),
+    })
+    expect(packageJson.dependencies).not.toHaveProperty('autoprefixer')
+    expect(packageJson.dependencies).not.toHaveProperty('postcss-import')
+    expect(packageJson.devDependencies).toMatchObject({
+      '@tailwindcss/postcss': expect.stringContaining('4.0.0'),
+    })
+  },
+)
+
+test(
+  'migrates a postcss setup using a json based config file',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "postcss": "^8",
+            "postcss-cli": "^10",
+            "postcss-import": "^16",
+            "autoprefixer": "^10",
+            "tailwindcss": "^3",
+            "@tailwindcss/upgrade": "workspace:^"
+          }
+        }
+      `,
+      '.postcssrc.json': json`
+        {
+          "plugins": {
+            "postcss-import": {},
+            "tailwindcss/nesting": "postcss-nesting",
+            "tailwindcss": {},
+            "autoprefixer": {}
+          }
+        }
+      `,
+      'tailwind.config.js': js`
+        /** @type {import('tailwindcss').Config} */
+        module.exports = {
+          content: ['./src/**/*.{html,js}'],
+        }
+      `,
+      'src/index.html': html`
+        <div class="bg-[--my-red]"></div>
+      `,
+      'src/index.css': css`
+        @tailwind base;
+        @tailwind components;
+        @tailwind utilities;
+      `,
+    },
+  },
+  async ({ fs, exec }) => {
+    await exec('npx @tailwindcss/upgrade')
+
+    await fs.expectFileToContain('src/index.css', css`@import 'tailwindcss';`)
+    await fs.expectFileToContain(
+      'src/index.html',
+      // prettier-ignore
+      js`
+        <div class="bg-[var(--my-red)]"></div>
+      `,
+    )
+
+    let jsonConfigContent = await fs.read('.postcssrc.json')
+    let jsonConfig = JSON.parse(jsonConfigContent)
+    expect(jsonConfig).toMatchInlineSnapshot(`
+      {
+        "plugins": {
+          "@tailwindcss/postcss": {},
+        },
+      }
+    `)
+
+    let packageJsonContent = await fs.read('package.json')
+    let packageJson = JSON.parse(packageJsonContent)
+    expect(packageJson.dependencies).toMatchObject({
+      tailwindcss: expect.stringContaining('4.0.0'),
+    })
+    expect(packageJson.dependencies).not.toHaveProperty('autoprefixer')
+    expect(packageJson.dependencies).not.toHaveProperty('postcss-import')
+    expect(packageJson.devDependencies).toMatchObject({
+      '@tailwindcss/postcss': expect.stringContaining('4.0.0'),
+    })
+  },
+)
+
 test(
   `migrates prefixes even if other files have unprefixed versions of the candidate`,
   {
@@ -297,7 +531,7 @@ test(
     },
   },
   async ({ exec, fs }) => {
-    await exec('npx @tailwindcss/upgrade -c tailwind.config.js')
+    await exec('npx @tailwindcss/upgrade')
 
     await fs.expectFileToContain('src/index.html', html`
         <div class="flex"></div>
@@ -335,7 +569,7 @@ test(
     },
   },
   async ({ exec, fs }) => {
-    await exec('npx @tailwindcss/upgrade -c tailwind.config.js')
+    await exec('npx @tailwindcss/upgrade')
 
     await fs.expectFileToContain(
       'src/index.html',

integrations/utils.ts

@@ -74,7 +74,7 @@ export function test(
 ) {
   return (only || (!process.env.CI && debug) ? defaultTest.only : defaultTest)(
     name,
-    { timeout: TEST_TIMEOUT, retry: debug ? 0 : 3 },
+    { timeout: TEST_TIMEOUT, retry: debug || only ? 0 : 3 },
     async (options) => {
       let rootDir = debug ? path.join(REPO_ROOT, '.debug') : TMP_ROOT
       await fs.mkdir(rootDir, { recursive: true })

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

@@ -4,10 +4,12 @@ import { globby } from 'globby'
 import path from 'node:path'
 import { help } from './commands/help'
 import { migrate as migrateStylesheet } from './migrate'
+import { migratePostCSSConfig } from './migrate-postcss'
 import { migrate as migrateTemplate } from './template/migrate'
 import { prepareConfig } from './template/prepare-config'
 import { args, type Arg } from './utils/args'
 import { isRepoDirty } from './utils/git'
+import { pkg } from './utils/packages'
 import { eprintln, error, header, highlight, info, success } from './utils/renderer'
 
 const options = {
@@ -98,6 +100,16 @@ async function run() {
     success('Stylesheet migration complete.')
   }
 
+  {
+    // PostCSS config migration
+    await migratePostCSSConfig(process.cwd())
+  }
+
+  try {
+    // Upgrade Tailwind CSS
+    await pkg('add tailwindcss@next', process.cwd())
+  } catch {}
+
   // Figure out if we made any changes
   if (isRepoDirty()) {
     success('Verify the changes and commit them to your repository.')