tailwind-v4-migration

Tailwind v3 to v4 Migration

Use these rules when migrating an existing Tailwind v3 project to v4. For a full interactive migration workflow, use the /tw-migrate skill.

Before Starting

Browser requirement: v4 requires Safari 16.4+, Chrome 111+, Firefox 128+. If the project needs older browser support, stay on v3.4.x.

Node.js requirement: The @tailwindcss/upgrade tool requires Node.js 20+. Tailwind v4 itself supports Node.js 18+.

Automated Upgrade Tool

Tailwind provides an automated upgrade tool that handles many changes:

npx @tailwindcss/upgrade

This tool:

• Converts @tailwind imports to @import "tailwindcss"
• Moves ! important modifiers to class end
• Updates arbitrary CSS variable syntax [--x] to (--x)
• Renames utility classes (shadow-sm to shadow-xs, etc.)
• Updates PostCSS config
• Attempts to convert tailwind.config.js to @theme

It does NOT handle all edge cases. Manual review is always required after running it.

Manual Migration Steps

Step 1: Update Dependencies

# Remove v3 packages
npm uninstall tailwindcss autoprefixer postcss-import

# Install v4 packages (choose one)
npm install -D tailwindcss @tailwindcss/vite       # Vite projects
npm install -D tailwindcss @tailwindcss/postcss     # PostCSS projects

Step 2: Update CSS Entry Point

Replace:

@tailwind base;
@tailwind components;
@tailwind utilities;

With:

@import "tailwindcss";

Step 3: Convert Configuration

Move tailwind.config.js theme values to @theme:

// OLD: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#ff6a00',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
}

/* NEW: in your CSS file */
@import "tailwindcss";

@theme {
  --color-brand: #ff6a00;
  --font-sans: "Inter", sans-serif;
}

If full conversion is not yet practical, bridge with @config:

@import "tailwindcss";
@config "../../tailwind.config.js";