Tailwind v4 Migration: 5 Critical Steps to Upgrade Safely

Tailwind v4 isn't a patch — it's a rewrite. Configuration moves from JavaScript into CSS, the build moves from PostCSS to Vite, and the engine gets roughly 10x faster.

That much change breaks things. Renamed utilities, dead directives, vanished configs — each one fails quietly, showing up as unstyled elements rather than build errors.

This guide gives you the five-step migration in order, the @theme mental model that replaces tailwind.config.js, and the visual-regression safety net that catches what automation misses.

The Big Shift: CSS-First Configuration With @theme

The core shift is simple: your design tokens move from JavaScript into CSS. Instead of theme.extend.colors in tailwind.config.js, you write @theme { --color-brand-500: oklch(...); } in your stylesheet. Tailwind then generates bg-brand-500, text-brand-500, and every other color utility from that one variable.

The same variable is simultaneously available as var(--color-brand-500) in your custom CSS. One definition feeds both systems — utilities and hand-written styles can never disagree about what 'brand' means.

Because tokens are plain CSS, they're inspectable in DevTools, composable with color-mix(), and shareable across projects as importable CSS files. Config values stopped being build-time secrets and became runtime citizens.

The 5-Step Migration Path in Order

Do it in this order and each step is verifiable. First, update dependencies: remove tailwindcss v3/postcss/autoprefixer where replaced, add tailwindcss v4 plus @tailwindcss/vite (or the CLI package). Node 20+ is required for the tooling.

Second, run the official upgrade tool — it rewrites dependencies, converts basic config to CSS, and fixes common template patterns. Review its diff like a human PR; it covers ~80%, not 100%.

Third, replace the entry CSS: @tailwind base/components/utilities becomes @import "tailwindcss" (first import in the file). Fourth, migrate remaining theme values to @theme and rewrite custom utilities with @utility. Fifth, screenshot-diff everything before shipping.

/* BEFORE (v3): entry.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* AFTER (v4): entry.css — @import must come first */
@import "tailwindcss";

@theme {
  --font-display: "Inter", system-ui, sans-serif;
  --color-brand-500: oklch(0.65 0.15 250);
  --color-brand-700: oklch(0.45 0.14 250);
  --breakpoint-3xl: 120rem;
}

/* usage: bg-brand-500, text-brand-700, font-display */
/* custom CSS: color: var(--color-brand-500); */

Build Pipeline Changes: Vite Plugin and Lightning CSS

The build plumbing changes alongside the config. In v4, Tailwind runs as a Vite plugin (@tailwindcss/vite) instead of a PostCSS plugin — your dependency bump is also a pipeline change. Update vite.config.ts to register the plugin and drop postcss.config.js if Tailwind was its only client.

Autoprefixer and postcss-import are generally unnecessary now: v4 handles vendor prefixing internally via Lightning CSS and bundles imports itself. Fewer config files, fewer version conflicts.

The payoff is speed. The rewritten engine parses sources and generates CSS on demand so efficiently that most projects compile in sub-10ms and even huge ones stay under 100ms. CI style steps effectively disappear from timing charts.

API Swaps: @utility, var(), and Dead Configs

Three API swaps bite almost everyone. @apply with !important patterns should move to @utility, which participates in variants and responsive prefixes properly. The theme() function in CSS is gone — use native var(--token) since every @theme value is a real CSS variable. And safelist config is largely unnecessary because v4's content detection is far more thorough.

Container queries deserve a look while you're here: v4 supports @container natively, so responsive-to-parent patterns that needed plugins in v3 now work out of the box.

Handle each swap with a project-wide search (theme(, @apply, safelist) and fix every hit before the regression pass. Stragglers hide in rarely-visited stylesheets.

/* v3 patterns */
/* .card { @apply shadow-sm bg-white text-black; } */
/* .btn { background: theme('colors.brand.500'); } */

/* v4 equivalents */
@utility btn-brand {
  background: var(--color-brand-500);
  color: white;
  padding: 0.5rem 1rem;
  border-radius: 0.375rem;
}
/* usage: <button class="btn-brand hover:btn-brand"> */

@custom-variant hocus (&:hover, &:focus);
/* usage: <a class="hocus:underline"> */

Browser Baseline and the OKLCH Palette Shift

This step is non-negotiable: v4 requires Safari 16.4+, Chrome 111+, and Firefox 128+. The framework depends on @property, color-mix(), and cascade layers at its core — older browsers don't just degrade, they break.

Check your analytics and support matrix before migrating. Enterprise and emerging-market audiences often still include older browsers; for them, staying on v3.4 is the correct professional call, not a failure.

Also note the default palette now uses OKLCH for perceptually uniform color. Slight shade shifts versus v3 are expected — that's another reason the visual regression pass matters. Some 'breakage' is just better color science.

Finishing Clean: Proof, Regression, and Handoff

Close it out cleanly. Keep @config pointing at tailwind.config.js until a build without it produces byte-identical CSS — that's your proof the token migration is complete. Then delete the JS file and celebrate with a smaller repo.

Run the full build with a cold cache, screenshot-diff all key pages at mobile, tablet, and desktop, and exercise interactive states (hover, focus, dark mode) that static screenshots miss.

Document the new token home for the team: @theme blocks in entry CSS, shared brand tokens as importable CSS files. Future theming work now happens in stylesheets, not JavaScript.