Tailwind CSS v4 Migration Complete Guide: New Engine, CSS-First Configuration, and Performance Leap

Tailwind CSS v4: Redefining Atomic CSS

v4 is not a gradual upgrade but an architectural rewrite—the new engine (Oxide) brings 10x build speed, and CSS-first configuration replaces JS configuration.

Dimension	v3	v4
Engine	PostCSS plugin	Rust engine (Oxide)
Configuration	`tailwind.config.js`	CSS `@theme` directive
Content Detection	`content` array	Auto-detection
Build Speed	Baseline	10x+
Container Queries	Plugin	Native support
3D Transforms	Plugin	Native support

1. New Engine: Oxide

Performance Comparison

Operation	v3	v4	Improvement
Full build (1000+ utilities)	~500ms	~50ms	10x
Incremental HMR	~50ms	~5ms	10x
Large project (500+ components)	~2s	~200ms	10x

Oxide is written in Rust and integrates into build tools via Wasm or native modules.

2. CSS-First Configuration

v3: JS Configuration File

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [require('@tailwindcss/typography')],
};

v4: CSS Configuration

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

@theme {
  --color-brand: #3b82f6;
  --font-sans: "Inter", sans-serif;
  --breakpoint-xs: 475px;
  --spacing-18: 4.5rem;
}

Advantages:

Configuration is CSS, IDE natively supports it
No JS runtime needed
Easier alignment with design systems

Custom Utilities

@theme {
  --animate-fade-in: fade-in 0.3s ease-out;
}

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

<div class="animate-fade-in">Fade-in effect</div>

3. Automatic Content Detection

v4 no longer requires manually configuring the content array—it automatically infers from project structure:

Framework	Detection Method
Next.js	Auto-scan `app/`, `src/`
Vite	Auto-scan `src/`
Nuxt	Auto-scan `components/`, `pages/`
General	Auto-scan project root

To exclude paths:

@import "tailwindcss" source("../src");
/* or exclude */
@import "tailwindcss" source("../src") not("../src/generated");

4. Native Container Query Support

v3 Required Plugin

plugins: [require('@tailwindcss-container-queries')]
// <div class="md:max-w-sm"> → @container

v4 Native Support

<div class="@container">
  <div class="@md:flex-row flex-col">
    Horizontal layout when container width >= md
  </div>
</div>

@theme {
  --container-md: 448px;
}

Container Query Class	Meaning
`@container`	Define container
`@sm:flex-row`	flex-row when container >= sm
`@md:grid-cols-2`	Two columns when container >= md
`@lg:hidden`	Hidden when container >= lg

5. Native 3D Transform Support

<div class="rotate-x-45 rotate-y-30 rotate-z-15
            perspective-500 translate-z-10
            scale-3d scale-x-110 scale-y-90">
  3D transform element
</div>

Class	CSS Property
`rotate-x-45`	`rotateX(45deg)`
`rotate-y-30`	`rotateY(30deg)`
`rotate-z-15`	`rotateZ(15deg)`
`perspective-500`	`perspective(500px)`
`translate-z-10`	`translateZ(10px)`
`scale-3d`	`scale3d()`
`backface-hidden`	`backface-visibility: hidden`

6. Migration Steps

Step 1: Upgrade Dependencies

npm install tailwindcss@next @tailwindcss/postcss@next

Step 2: Update PostCSS Configuration

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

Step 3: Migrate Configuration Files

/* app.css - New configuration */
@import "tailwindcss";

/* Migrate v3's theme.extend */
@theme {
  /* colors */
  --color-primary: #3b82f6;
  --color-secondary: #10b981;

  /* fontFamily */
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* spacing */
  --spacing-18: 4.5rem;

  /* breakpoints */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

Step 4: Handle Breaking Changes

v3 Syntax	v4 Syntax	Notes
`bg-opacity-50`	`bg-blue-500/50`	Opacity modifier
`overflow-ellipsis`	`text-ellipsis`	Renamed
`shadow-outline`	Custom	Removed

Step 5: Remove Unnecessary Plugins

Plugin	v4 Replacement
`@tailwindcss/container-queries`	Native support
`@tailwindcss/3d`	Native support
`@tailwindcss/line-clamp`	Native support (`line-clamp-3`)

7. Vite Integration

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

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

No more PostCSS middleware needed—Vite plugin integrates directly, faster.

8. Common Migration Pitfalls

1. Custom Colors Not Working

/* Wrong: missing --color- prefix */
@theme {
  --brand: #3b82f6;  /* Won't generate text-brand, bg-brand */
}

/* Correct */
@theme {
  --color-brand: #3b82f6;  /* Generates text-brand, bg-brand, border-brand */
}

2. @apply Behavior Changes

/* v3: @apply can use any utility */
/* v4: @apply only supports static utilities, not dynamic values */

.button {
  @apply bg-blue-500 text-white;  /* ✅ */
  @apply bg-[#123456];            /* ❌ Write direct CSS instead */
}

3. Prefix Mode Changes

/* v3: prefix in JS config */
/* v4: prefix in CSS */
@import "tailwindcss" prefix(tw);
/* Generates tw-flex, tw-text-lg, etc. */

9. Recommended Migration Strategy

New projects use v4 directly: Zero migration cost
Existing projects migrate gradually: v3 and v4 can coexist in different entry points
Migrate configuration first: Convert JS config to CSS @theme
Handle breaking changes next: Use official codemod
Finally remove plugins: Replace with native features

# Official codemod
npx @tailwindcss/upgrade@next