How I migrated a large Next.js project from Tailwind CSS v3 to v4

Tailwind CSS v4 migration in a Next.js project is not a one-command upgrade. I ran it on a mid-size marketing site — around 180 components, a design system with custom tokens, and a Sanity-powered content layer — and it took a full day plus a few hours of cleanup. Here is exactly what I changed and where it got awkward.

What actually changed between v3 and v4

The headline change is that the config file is gone. In v4 there is no tailwind.config.ts. Your design tokens live in CSS using @theme inside your global stylesheet. PostCSS integration also changed: v4 ships its own dedicated PostCSS plugin rather than piggybacking on tailwindcss as a generic plugin.

A handful of utilities were renamed or removed. The bg-opacity-* and text-opacity-* shorthand classes are gone — they now map to the slash syntax (bg-blue-500/50). The transform and filter utility stubs that v3 required to enable GPU compositing are also removed because v4 applies those automatically. The ring default width changed from 3px to 1px.

On the positive side: v4 is dramatically faster at build time (the Rust engine replaces the Node scanning pass), and the CSS output on a large project I measured dropped by ~18% after removing now-redundant @layer scaffolding.

Step 1 — update packages and swap the PostCSS plugin

Remove the old packages and install the new ones:

npm remove tailwindcss postcss autoprefixer
npm install tailwindcss@^4 @tailwindcss/postcss@^4

Then update postcss.config.mjs. The old config used tailwindcss as a plugin key. V4 uses @tailwindcss/postcss:

// postcss.config.mjs
/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default config;

Note: autoprefixer is no longer needed as a separate entry — v4 bundles its own prefix handling. Leaving it in does not break anything but it adds a redundant pass.

Step 2 — move config into CSS with @theme

Delete tailwind.config.ts. Open your globals.css (or whatever your root stylesheet is) and move tokens into an @theme block. The @import "tailwindcss" line replaces the old @tailwind base/components/utilities directives.

/* app/globals.css */
@import "tailwindcss";

@theme {
  --color-brand-500: oklch(62% 0.19 250);
  --color-brand-600: oklch(55% 0.21 250);
  --color-surface: oklch(98% 0.005 250);

  --font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --radius-card: 0.75rem;
  --radius-button: 0.375rem;

  --spacing-section: 5rem;

  --breakpoint-3xl: 1920px;
}

Every CSS custom property inside @theme becomes a Tailwind utility automatically. --color-brand-500 generates bg-brand-500, text-brand-500, border-brand-500, and so on. You do not need to extend anything.

The one gotcha: if you had theme.extend.colors keyed with camelCase (e.g. brandPrimary) your class names were bg-brandPrimary. In v4 the property name drives the class name directly, so you want kebab-case keys (--color-brand-primary → bg-brand-primary). I had about 30 class references to find-and-replace across the codebase for this alone.

Step 3 — handle dropped and renamed utilities

Run the project and check the browser console and your CI visual diff. The places that broke for me:

Opacity utilities. Any bg-opacity-* or text-opacity-* class throws no error — they just silently produce no CSS. I ran a grep to find them:

grep -r 'bg-opacity\|text-opacity\|border-opacity' ./components ./app --include='*.tsx'

Replace with the slash syntax: bg-blue-600 bg-opacity-75 becomes bg-blue-600/75. This is cleaner anyway.

Ring width default. Any component using bare ring (without a width modifier) now renders a 1px ring instead of 3px. Most focus rings looked too thin after migration. I added ring-2 or ring-3 explicitly wherever the design required the heavier ring.

Transform and filter stubs. Removing transform from a class list should be fine — v4 no longer requires it. But if any component was conditionally toggling transform to enable/disable GPU promotion, that logic is now a no-op and can be deleted.

Arbitrary values with CSS variables. In v3 you could write bg-[var(--color-brand)]. This still works in v4 but if the variable is inside @theme, you can just use the generated utility directly and remove the arbitrary value syntax.

Step 4 — fix content path scanning

V4 auto-detects content paths by scanning the project from the stylesheet's directory. For most Next.js projects this works out of the box because globals.css sits inside app/ which is a sibling to components/. If you have a monorepo or unconventional folder layout and classes are getting purged incorrectly, you can hint explicitly:

/* app/globals.css */
@import "tailwindcss";
@source "../packages/ui/src";
@source "../packages/marketing/src";

@theme { … }

@source is the v4 replacement for the content array in tailwind.config.ts.

Rough edges I actually hit in production

Turbopack + v4 HMR. On Next.js 15 with --turbopack, hot reload of the @theme block was occasionally slow (2–3 second delay) compared to changing a component class. Not a showstopper but noticeable during token-heavy design iteration. Webpack mode was snappier for this particular workflow.

Third-party component libraries. I use Radix primitives with a custom Tailwind-based design system. The components themselves were fine, but a ShadCN-style component file that imported its own tailwind-merge config needed the class name mapping updated to match the new token names.

PostCSS plugin order. I had cssnano in the PostCSS config for production builds. Placing it after @tailwindcss/postcss worked correctly; placing it before caused some @theme variables to be stripped in the minification pass. Always put @tailwindcss/postcss first.

@apply with v3-only utilities. Any @apply bg-opacity-50 inside a CSS file throws a build error in v4 because the utility no longer exists. These are easier to track down than JSX class names because the build fails loudly.

Was it worth it

For this project: yes. Build time for the CSS pass went from ~1.1s to ~180ms. The stylesheet size dropped from 42 kB to 34 kB (brotli: 8.2 kB to 6.7 kB). The CSS-based config is actually nicer to work with once you stop reaching for the old config file — design tokens are colocated with where they are consumed rather than in a separate JS tree.

The migration is mechanical and grep-able. Budget half a day for a medium-size project, a full day if you have a large design token surface or heavy use of the opacity shorthand utilities.

推荐订阅源

DEV Community