Tailwind CSS v4: What Actually Changed and How I Migrated Two Projects

Headline: Tailwind v4 is the most significant rewrite since the framework launched — CSS-first config, Lightning CSS under the hood, container queries built-in, and no more tailwind.config.js . I migrated two production projects and here's what actually broke and what the upgrade tool misses. Tailwind CSS v4 arrived with a steeper upgrade curve than most version bumps in the JS ecosystem. The configuration story changed completely. The build engine changed. Several features that previously required plugins are now built-in. The headline change: no more tailwind.config.js In v3, configuration lived in a JavaScript file — theme extensions, plugins, content paths. In v4, it moves into your CSS: @import "tailwindcss" ; @theme { --color-brand : #6366f1 ; --spacing-18 : 4.5rem ; } Theme tokens become CSS custom properties under @theme , and Tailwind generates utility classes automatically. The content array is gone — v4 detects source files automatically. The new engine: Lightning CSS Tailwind v4 ships with Lightning CSS replacing PostCSS as the default: Build times drop significantly (cold rebuild went from ~8s to under 3s on the dashboard) CSS nesting works natively without a plugin Modern CSS features like color-mix() , @starting-style , oklch are transpiled automatically autoprefixer is no longer needed New features built-in Container queries — native in v4, no plugin needed: <div class= "@container" > <div class= "grid grid-cols-1 @sm:grid-cols-2" > ... </div> </div> 3D transforms — rotate-x-45 , rotate-y-12 , perspective-1000 for card flip effects without inline styles. Dynamic spacing — p-13 , mt-22 work without explicit definition. Migration: the upgrade tool and what it misses npx @tailwindcss/upgrade@next The codemod handles the mechanical parts. What it missed: Custom plugins — the JS plugin API changed; non-trivial v3 plugins need a rewrite to the new @plugin / @utility API theme() calls in CSS — replace theme('colors.zinc.900') with var(--color-zinc-900) ; gr