Tailwind CSS v4: new features and migration guide

Tailwind CSS v4 represents the most significant architectural overhaul since the framework launched. Built on a new high-performance Rust engine, it removes the PostCSS dependency, introduces a CSS-first configuration model, and delivers substantially faster build times. This guide covers every major change and how to migrate your existing projects.

What's New in Tailwind CSS v4

Tailwind CSS v4 was released in early 2025 and fundamentally changes how the framework is configured, compiled, and integrated into build pipelines. The headline changes are: a new Oxide engine written in Rust that makes full builds up to 10× faster and incremental builds up to 100× faster; a CSS-first configuration system that replaces tailwind.config.js; native CSS cascade layers; first-class container query support; and a completely overhauled theming system using CSS custom properties.

The Oxide Engine: Rust-Powered Performance

The Oxide engine replaces the JavaScript-based scanner that Tailwind used in v3. It is written in Rust and integrated via a native Node.js module, which means the template scanning and CSS generation pipeline runs at native speed. For large projects with thousands of components, this translates to full build times dropping from 3–8 seconds to under 300ms, and incremental HMR updates becoming near-instantaneous.

Oxide also changes how Tailwind detects classes. In v3, you had to configure content paths explicitly. In v4, Oxide uses a smarter file detection algorithm that automatically finds templates based on your project structure, eliminating one of the most common configuration mistakes in v3 projects.

CSS-First Configuration

The biggest workflow change in v4 is replacing tailwind.config.js with a CSS-first configuration model. All theme customisation now happens directly in your CSS file using @theme, @utility, and @variant directives.

/* tailwind.css */
@import "tailwindcss";

@theme {
  --font-sans: "Inter", sans-serif;
  --color-brand: oklch(55% 0.25 265);
  --color-brand-hover: oklch(45% 0.25 265);
  --spacing-18: 4.5rem;
  --radius-xl: 1rem;
}

@utility btn-primary {
  @apply px-6 py-3 bg-brand text-white rounded-xl font-medium;
  &:hover { @apply bg-brand-hover; }
}

This approach has several advantages over the JavaScript config file: co-location of design tokens with CSS, better IDE integration, easier sharing of theme tokens across stylesheets, and alignment with the direction of the web platform (CSS custom properties are now the standard theming primitive).

The New Theme System

In v4, every design token in the default theme is exposed as a CSS custom property under the -- namespace. This means Tailwind's spacing scale, colour palette, typography scale, and breakpoints are all available as CSS variables throughout your stylesheets, not just in Tailwind utilities.

First-Class Container Queries

Container queries are now fully supported in v4 without any plugin. Use the @container variant with responsive-style syntax:

<div class="@container">
  <div class="grid @md:grid-cols-2 @lg:grid-cols-3 gap-4">
    <!-- Responsive to container width, not viewport -->
  </div>
</div>

This is a landmark improvement for component-driven design. Previously, building components that respond to their container's width required either the @tailwindcss/container-queries plugin (v3) or custom CSS. In v4, container queries are first-class syntax, making it trivial to build truly reusable layout components.

CSS Cascade Layers

v4 wraps Tailwind's generated CSS in native CSS cascade layers (@layer base, @layer components, @layer utilities). This solves one of the long-standing complaints about Tailwind: specificity conflicts with existing CSS. With cascade layers, you can define your own styles at a higher layer and they will reliably override Tailwind utilities without needing !important or specificity gymnastics.

Migration Guide: v3 to v4

Enterprise Adoption Considerations

For enterprise design systems, v4 introduces important architectural decisions. The CSS-first configuration model is a significant departure from the JavaScript config teams may have spent years building around. Migration requires updating build pipelines, IDE integrations, design token pipelines (if you generate tailwind.config.js from a design tool like Figma Tokens or Style Dictionary), and any custom plugins.

The performance improvements make v4 compelling even for teams that have heavily customised v3 setups. Build time improvements alone justify migration for large projects where slow rebuilds were impacting developer productivity. Plan a phased migration: update the CLI and engine first, then progressively migrate configuration to the new CSS-first model.