Tailwind CSS v4: What Changed and Why It Matters

Tailwind CSS v4 is a ground-up rewrite. The new engine, built in Rust and powered by Lightning CSS, is up to 10x faster than v3 in full builds and over 100x faster for incremental rebuilds. But speed is not the headline. The real shift is architectural: configuration moves from tailwind.config.js into your CSS files using native CSS syntax. If you have been putting off the upgrade, here is everything you need to know.

The Big Changes

The JavaScript configuration file is gone. In v4, you configure Tailwind directly in CSS using @theme directives. This means your design tokens live alongside your styles, not in a separate build-tool config. The new engine automatically detects your template files without explicit content paths. It scans your project for class usage, making the content array unnecessary in most setups.

PostCSS is no longer required as a default. Tailwind v4 ships as a standalone tool and a first-class Vite plugin. If you are on Vite (and you should be for new projects), setup is a single import in your CSS entry point.

Installation and Setup

# Install as a Vite plugin (recommended)
npm install tailwindcss @tailwindcss/vite

# Or use the PostCSS plugin for existing PostCSS pipelines
npm install tailwindcss @tailwindcss/postcss

For Vite, register the plugin in vite.config.ts:

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

Then import Tailwind in your main CSS file:

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

That is the entire setup. No config file, no content paths, no PostCSS config. The engine handles detection automatically.

CSS-First Configuration with @theme

Design tokens now live in your CSS using the @theme directive. This replaces the theme.extend object from tailwind.config.js:

@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --color-brand-light: #818cf8;
  --color-brand-dark: #4f46e5;
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}

/* Now use anywhere: bg-brand, text-brand-light, font-display, 3xl:grid-cols-4 */

Every CSS variable you define under @theme becomes a utility class automatically. Define --color-mint: #10b981 and you instantly get bg-mint, text-mint, border-mint, ring-mint, and every other color utility. The mapping is convention-based: --color-* maps to color utilities, --font-* maps to font families, --spacing-* maps to spacing, and so on.

New Utility Classes

Tailwind v4 adds first-class support for modern CSS features:

<!-- Container queries -->
<div class="@container">
  <div class="@sm:grid-cols-2 @lg:grid-cols-3">
    <!-- Responds to container width, not viewport -->
  </div>
</div>

<!-- color-mix() for opacity -->
<div class="bg-brand/50"> <!-- 50% opacity of your brand color --></div>

<!-- 3D transforms -->
<div class="rotate-x-12 rotate-y-6 perspective-800">
  <!-- True 3D card effect -->
</div>

<!-- Logical properties for RTL support -->
<div class="ms-4 me-2 ps-6 pe-4">
  <!-- margin-inline-start, margin-inline-end, etc. -->
</div>

Container queries alone are a significant addition. They let components respond to their own container size rather than the viewport, which is critical for reusable component libraries and dashboard layouts where panels resize independently.

Migrating from v3

Tailwind ships an automated upgrade tool that handles most of the migration:

npx @tailwindcss/upgrade

The tool converts your tailwind.config.js theme values into @theme CSS directives, updates deprecated class names, and adjusts your build configuration. Manual attention is needed for custom plugins (the plugin API changed), complex theme() function usage in CSS, and any JavaScript-based dynamic configuration. Test thoroughly after running the tool.

Should You Upgrade Now?

For new projects, use v4 without hesitation. The developer experience improvement is substantial, and the Vite plugin integration is seamless. For existing v3 projects, the upgrade tool makes migration manageable, but budget time for plugin compatibility testing. The performance gains alone justify the effort for large codebases where rebuild times affect developer velocity.

Further reading: Tailwind CSS v4 Docs | v3 to v4 Upgrade Guide | Tailwind v4 Announcement