Tailwind CSS v4: What's New, What Changed, and How to Migrate

Tailwind CSS v4 represents the most significant architectural shift since the utility-first framework launched. The JavaScript config file is gone. The CSS @import configuration is in. The Oxide engine replaces the Node.js-based processing pipeline. For most projects, this means 5–10x faster full builds and 100x+ faster incremental builds. The migration path is manageable.

The New CSS-First Configuration

In v4, you configure Tailwind directly in your CSS file using @import and @theme directives. Your design tokens are CSS custom properties. There is no tailwind.config.js. This isn't just aesthetics — your theme values are now directly usable as CSS variables throughout your stylesheets without any special syntax.

```css @import "tailwindcss";

@theme { --color-brand: oklch(65% 0.25 250); --font-sans: "Inter Variable", sans-serif; --radius-card: 1.5rem; } ```

The Oxide Engine: Performance at Scale

The Oxide engine rewrites the CSS parsing pipeline in Rust, eliminating the Node.js overhead for class scanning. For a large codebase with thousands of components, this means full rebuilds in under 100ms instead of 2–5 seconds. Incremental rebuilds (on save during development) drop to <5ms. The development experience improvement is immediately perceptible.

New Utilities Worth Knowing

v4 ships with several new utility categories that previously required plugins: `field-sizing-content` for auto-resizing textareas, container queries directly in Tailwind classes (`@sm:flex`), 3D transform utilities (`rotate-x-45`, `translate-z-8`), and `text-shadow` utilities. The color palette has been updated to use OKLCH throughout, providing more perceptual uniformity across the color scale.

Migration from v3

The official upgrade tool handles the majority of breaking changes automatically: `npx @tailwindcss/upgrade`. Review the output carefully — the tool migrates config to CSS @theme, updates deprecated class names (`shadow-sm` is now `shadow-xs`), and adjusts JIT mode references. Most projects complete migration in under an hour.