Tailwind CSS v4: What Changed and How to Upgrade

What Is New in Tailwind CSS v4?

Tailwind CSS v4 is a ground-up rewrite that introduces a CSS-first configuration approach, the Lightning CSS engine for significantly faster build times, native CSS variables for all design tokens, and a new @import 'tailwindcss' syntax. The theme is no longer defined in a JavaScript config file — instead, it lives in your CSS file using CSS custom properties. This makes Tailwind feel more integrated with the web platform.

CSS-First Configuration

In Tailwind v4, you configure your theme in CSS using @theme: @theme { --color-brand: oklch(55% 0.2 250); --font-sans: 'Inter', sans-serif; }. These CSS custom properties become Tailwind utilities automatically — bg-brand, text-brand, font-sans. No more tailwind.config.js for most use cases. This approach makes design tokens available as CSS variables throughout your stylesheets, not just in Tailwind utility classes.

Lightning CSS Engine

Tailwind v4 uses Lightning CSS as its internal CSS processing engine, replacing PostCSS for core transformations. Lightning CSS is written in Rust and is significantly faster — build times for large projects drop dramatically. It handles vendor prefixing, nested CSS (natively supported in modern browsers but transpiled for older ones), and CSS module transforms. You still configure PostCSS plugins for other transformations.

Dynamic Utility Values

Tailwind v4 supports dynamic utility values more flexibly. Use arbitrary values like w-[347px] and gap-[13px] as before, but also use CSS variable references: bg-(--my-color). The new variant syntax is cleaner, and container queries are built in with @container. Dynamic utilities no longer require the safelist config for purging — v4's engine detects dynamic class usage intelligently.

Breaking Changes and Migration

Migrating from Tailwind v3 to v4 requires some adjustments. The tailwind.config.js is no longer used for theme — move your customizations to @theme in CSS. Some utility class names changed (ring-3 is now ring-[3px], etc.). The @apply directive still works but is discouraged in v4. Run the official upgrade tool: npx @tailwindcss/upgrade to automate most migration steps in your project.

Performance and Developer Experience Improvements

Tailwind v4's incremental build mode makes development extremely fast — only changed files trigger CSS regeneration. The new oxide engine eliminates the need for a content configuration (files to scan) — Tailwind automatically detects your template files. IntelliSense support in the Tailwind CSS VS Code extension is fully updated for v4 syntax. Overall, v4 is a significant improvement in both build performance and configuration ergonomics.