Migrating v3 → v4

What changes when upgrading an existing Tailwind v3 codebase to the CSS-first v4 architecture.

4 min read Level 3/5 #tailwind#migration#v4

What you'll learn

Run the official upgrade tool
Move tailwind.config.js into @theme
Adjust renamed utilities and changed defaults

Tailwind v4 moves configuration from JavaScript into CSS. The official tool automates most of the upgrade, but a few changes deserve a manual review.

Run the Upgrade Tool

Start with the codemod, which rewrites directives, migrates config, and renames utilities for you:

npx @tailwindcss/upgrade

Commit first, run it on a clean branch, then review the diff.

Directives and Config

The three @tailwind directives collapse into one import, and theme.extend becomes @theme tokens:

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* v4 */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 256);
}

The PostCSS setup changes too: use @tailwindcss/postcss, or switch to the @tailwindcss/vite plugin.

Renamed Utilities and Defaults

Watch for the renames the tool applies and verify them visually:

shadow-sm → shadow-xs, shadow → shadow-sm
outline-none → outline-hidden
rounded → rounded-sm, blur → blur-sm

Defaults also shifted: the default border and ring color is now currentColor instead of gray, and @apply in separate CSS files may need @reference "..."; to see your theme. Audit borders and rings after upgrading.

Going Further →