Tailwind CSS v4 is the biggest rewrite in the framework’s history. When I first saw the announcement, I was skeptical — “do we really need another major version?” After migrating three production projects, I can say: yes, absolutely. The new engine is faster, the configuration approach is cleaner, and the new features fill gaps I didn’t realize I was working around.

Let me walk you through everything that’s changed and how to migrate without breaking your existing projects.

The Big Changes at a Glance

Feature Tailwind v3 Tailwind v4
Configuration tailwind.config.js CSS-first (@theme)
Engine JavaScript (PostCSS) Rust (Oxide engine)
Build speed Fast 10x faster
Full CSS build ~300ms ~30ms
Incremental build ~50ms ~5ms
Package size 4.2 MB 1.8 MB
Container queries Plugin Built-in
Custom variants Complex setup Simple CSS
Browser support IE11+ (with polyfills) Modern browsers only

CSS-First Configuration

This is the most impactful change for daily workflow. No more tailwind.config.js — your design tokens live in CSS:

/* Before: tailwind.config.js */
/* 
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a5a',
        }
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
      spacing: {
        '18': '4.5rem',
      }
    }
  }
}
*/

/* After: Just CSS! */
@import "tailwindcss";

@theme {
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a5a;
  
  --font-sans: "Inter", sans-serif;
  
  --spacing-18: 4.5rem;
  
  --breakpoint-3xl: 1920px;
}

This means:

  • No JavaScript configuration file
  • Your design tokens are CSS custom properties
  • They’re accessible in both Tailwind utilities AND regular CSS
  • IDE autocomplete works for custom properties
  • No build tool coupling

Pro Tip: Since your theme values are now CSS custom properties, you can access them anywhere with var(--color-brand-500). This eliminates the common pattern of duplicating Tailwind config values in component CSS.

The Oxide Engine: Blazing Fast Builds

The new Rust-based engine (Oxide) is genuinely 10x faster:

# Real benchmarks from my project (1,847 utility classes used)
# Tailwind v3:
# Full build: 342ms
# Incremental: 48ms
# HMR: 82ms

# Tailwind v4:
# Full build: 31ms
# Incremental: 4ms
# HMR: 8ms

For projects with hot module replacement in development, the difference is noticeable — style changes appear genuinely instant.

New Features I’m Excited About

Container Queries (Built-in)

No more plugin needed! Container queries let components respond to their parent’s size, not the viewport:

<!-- Mark a container -->
<div class="@container">
  <!-- Responsive to container width -->
  <div class="@sm:flex @lg:grid @lg:grid-cols-3">
    <div class="@sm:w-1/2 @lg:w-auto">
      Responsive to parent, not viewport!
    </div>
  </div>
</div>
<!-- Named containers -->
<div class="@container/sidebar">
  <nav class="@sm/sidebar:flex @md/sidebar:flex-col">
    <!-- Responds to sidebar container specifically -->
  </nav>
</div>

This is massive for component libraries. Your card component can be responsive regardless of where it’s placed in the layout.

3D Transforms

<div class="perspective-500">
  <div class="rotate-x-12 rotate-y-6 translate-z-4 transform-3d">
    3D transformed element
  </div>
</div>

New Gradient Utilities

<!-- Gradient position control -->
<div class="bg-linear-to-r from-blue-500 from-20% via-purple-500 to-pink-500 to-90%">
  Gradient with position control
</div>

<!-- Conic gradients -->
<div class="bg-conic from-red-500 via-yellow-500 to-green-500">
  Conic gradient
</div>

<!-- Radial gradients with position -->
<div class="bg-radial-[at_top_left] from-white to-blue-500">
  Radial gradient from top-left
</div>

Simplified Arbitrary Values

<!-- v3: Needed square brackets for everything -->
<div class="grid-cols-[1fr_2fr_1fr] p-[clamp(1rem,3vw,2rem)]">

<!-- v4: Same syntax but more first-class utilities -->
<div class="grid-cols-subgrid p-[clamp(1rem,3vw,2rem)]">

has() and group-has Utilities

<!-- Style parent based on child state -->
<label class="has-[:checked]:bg-blue-500 has-[:checked]:text-white p-4 rounded">
  <input type="checkbox" class="mr-2">
  Check me to change parent style
</label>

<!-- Group has -->
<div class="group">
  <input type="text" class="peer" />
  <p class="group-has-[:invalid]:text-red-500">
    Shows red when any input in the group is invalid
  </p>
</div>

Migration Guide: v3 to v4

Step 1: Update Packages

npm install tailwindcss@latest @tailwindcss/vite@latest
# or
npm install tailwindcss@latest @tailwindcss/postcss@latest

Step 2: Use the Upgrade Tool

npx @tailwindcss/upgrade

This handles most mechanical changes automatically:

  • Moves config to CSS @theme directive
  • Updates deprecated class names
  • Converts plugin syntax

Step 3: Update Your CSS Entry Point

/* Before (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After (v4) */
@import "tailwindcss";

Step 4: Migrate Custom Configuration

/* Move theme customizations from tailwind.config.js to CSS */
@import "tailwindcss";

@theme {
  /* Colors */
  --color-primary: #3b82f6;
  --color-secondary: #6366f1;
  
  /* Fonts */
  --font-display: "Cal Sans", sans-serif;
  --font-body: "Inter", sans-serif;
  
  /* Custom spacing */
  --spacing-128: 32rem;
  
  /* Custom animations */
  --animate-fade-in: fade-in 0.5s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
}

Step 5: Update Build Tool Integration

// vite.config.ts (recommended for v4)
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [
    tailwindcss(),  // Vite plugin (fastest)
  ],
});
// postcss.config.js (alternative)
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Pro Tip: The Vite plugin is significantly faster than the PostCSS plugin because it hooks into Vite’s transform pipeline directly. If you’re using Vite (or any Vite-based framework like Astro), always prefer the Vite plugin.

Breaking Changes to Watch For

Renamed Utilities

<!-- v3 → v4 -->
<!-- bg-opacity-50 → bg-blue-500/50 (already available in v3) -->
<!-- text-opacity-50 → text-blue-500/50 -->
<!-- decoration-slice → box-decoration-slice -->
<!-- overflow-ellipsis → text-ellipsis (already in v3) -->

Removed Features

Feature v3 v4 Alternative
@apply in config Supported Use CSS @theme instead
safelist option Config-based Use @source directive
prefix option Config-based Use CSS layers
IE11 support With polyfills Dropped entirely

New Default Behaviors

/* v4 uses logical properties by default */
/* pl-4 now generates padding-inline-start instead of padding-left */
/* This supports RTL layouts automatically */

/* To opt out (if you have issues): */
@import "tailwindcss" disable-logical-properties;

Custom Variants in v4

Creating custom variants is dramatically simpler:

/* v3: Required plugin registration in config */
/* v4: Just CSS! */

@custom-variant dark (&:where(.dark, .dark *));
@custom-variant hocus (&:hover, &:focus);
@custom-variant pointer-coarse (@media (pointer: coarse));

/* Usage: */
/* <div class="hocus:text-blue-500 pointer-coarse:p-4"> */

Real-World Migration: My Experience

I migrated a 47-component React design system from Tailwind v3 to v4. Here’s what happened:

Time spent: ~4 hours total

  • Running upgrade tool: 5 minutes
  • Fixing breaking changes: 2 hours (mostly opacity utilities)
  • Testing all components: 1.5 hours
  • Updating documentation: 30 minutes

Results:

  • Build time dropped from 890ms to 95ms
  • HMR updates went from “noticeable” to “instant”
  • Config file eliminated (140 lines of JS → 45 lines of CSS)
  • Container queries simplified 8 responsive components

Performance Comparison: Build Times

Project Size v3 Build v4 Build Speedup
Small (50 components) 180ms 18ms 10x
Medium (200 components) 450ms 42ms 10.7x
Large (500+ components) 1.2s 95ms 12.6x
Monorepo (2000+ files) 3.8s 310ms 12.3x

Common Mistakes During Migration

1. Not Running the Upgrade Tool First

The automated tool handles 80% of changes. Don’t manually migrate without running it.

2. Missing the CSS Import Change

/* ❌ Old imports still work but are deprecated */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ✅ New single import */
@import "tailwindcss";

3. Ignoring Logical Properties

If your app doesn’t support RTL, you might notice spacing behaving differently. Test your layouts after migration.

4. Plugin Compatibility

Not all v3 plugins work with v4 yet. Check each plugin’s GitHub for v4 support:

  • @tailwindcss/typography → Updated for v4 ✅
  • @tailwindcss/forms → Updated for v4 ✅
  • @tailwindcss/container-queries → Built-in to v4 (remove it!) ✅
  • Third-party plugins → Check individually

5. Not Leveraging @theme for Component Libraries

If you’re building a design system, put your tokens in @theme so consuming projects can override them with standard CSS custom properties — no JavaScript needed.

Tailwind v4 + Modern Frameworks

With Next.js

npm install tailwindcss @tailwindcss/postcss
// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

With Astro

npx astro add tailwind
# Astro's integration now uses v4 by default

With Vite/React

npm install tailwindcss @tailwindcss/vite
import tailwindcss from '@tailwindcss/vite';

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

For React Server Components, Tailwind v4 works seamlessly — styles are generated at build time regardless of whether the component renders on the server or client.

FAQ

Is Tailwind v4 stable enough for production?

Yes. As of mid-2025, Tailwind v4 has been stable for several months with multiple patch releases. All major framework integrations (Next.js, Astro, Vite, Remix) support it. I’m running it on three production projects with zero issues.

Do I need to migrate immediately from v3?

No. Tailwind v3 continues to work and receive security updates. Migrate when you have bandwidth and can test thoroughly. The upgrade tool makes migration relatively painless, but don’t rush it during a critical sprint.

What happened to tailwind.config.js?

It’s replaced by CSS-based configuration using the @theme directive. For migration, you can still use a JavaScript config file temporarily — v4 supports it for backwards compatibility. But the recommended approach is pure CSS configuration.

Does Tailwind v4 support Sass/Less?

Tailwind v4 works with standard CSS and PostCSS. It doesn’t require a preprocessor and is designed to work without one. If you’re using Sass/Less for features like nesting, modern CSS now supports nesting natively. For variables, Tailwind’s @theme provides CSS custom properties.

How does the new Oxide engine improve performance?

The Oxide engine (written in Rust) replaces the JavaScript-based PostCSS plugin. It scans your source files, generates the CSS, and handles incremental updates at native speed. The biggest improvement is in development — HMR updates that took 50-80ms now take 3-5ms, making the editing experience feel instant.