Tailwind CSS v4: What Changed and How to Migrate Your Project

Tailwind CSS v4 is the most significant change to the framework since its initial release. The JavaScript config file is gone, replaced by CSS-first configuration using @theme. The PostCSS plugin is gone, replaced by a dedicated Vite plugin and a lightning-fast Rust-based engine. I've migrated three production projects already — here's the complete picture.

The Biggest Change: No More tailwind.config.js

Everything that lived in tailwind.config.js now lives in your CSS file using @theme. Custom colors, fonts, spacing, breakpoints — all defined as CSS variables inside the @theme block. This is actually a better mental model: your design tokens live in CSS where they belong, and you can reference them directly in regular CSS without Tailwind utility classes.

/* v4: globals.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.6 0.2 250);
  --color-brand-dark: oklch(0.45 0.2 250);
  --font-sans: 'Inter', sans-serif;
  --radius-card: 1rem;
  --breakpoint-xs: 30rem;
}

The @apply Migration

@apply still works in v4, but many projects over-use it as a way to avoid learning the utility classes properly. In v4 I've largely replaced @apply blocks with CSS using the native custom properties that @theme exposes. This produces more portable CSS that doesn't depend on Tailwind being present in every file.

New Variant Syntax

• Arbitrary variants now use the same syntax as regular variants: group-[.is-active]:opacity-100
• Starting style variant (starting:) for entry animations without JavaScript
• not-* variant for :not() pseudo-class: not-disabled:cursor-pointer
• inert: variant for targeting inert elements in modals and overlays

Performance Impact

The Oxide engine (Rust) is approximately 5x faster than the v3 engine on large projects. Full rebuilds that took 800ms in v3 take under 150ms in v4. Incremental builds are nearly instant. For large design systems or projects with many template files, this is a meaningful developer experience improvement.

Migration Approach

The Tailwind team provides an automated upgrade tool: npx @tailwindcss/upgrade. It converts your tailwind.config.js to @theme directives, updates your PostCSS config to use the new plugin, and flags utilities that changed. Run it, review the diff carefully (especially custom configurations), fix the flagged items, and run your test suite. I've found the tool handles 90% of the migration — the remaining 10% is project-specific customization that needs manual review.