Upgrade Guide

​

Should you upgrade?

• 5x faster full builds and over 100x faster incremental builds
• Zero configuration with automatic content detection
• CSS-first configuration using native CSS features
• Modern CSS features like cascade layers, @property, and color-mix()
• First-party integrations including a Vite plugin and CLI
• Modernized color palette with P3 color support
• Container queries and new 3D transforms built-in

​

Before you upgrade

​

Prerequisites

1. Ensure you’re on Tailwind CSS v3.x - The upgrade tool only supports migrating from v3 to v4
2. Commit your changes - The upgrade tool requires a clean git directory
3. Backup your project - While the tool is robust, having a backup is always wise
4. Review your dependencies - Some third-party plugins may need updates

​

Version compatibility

• Your installed version matches your package.json
• You’re running Tailwind CSS v3.x (not v2 or earlier)
• All dependencies are properly installed

Version mismatch

- "tailwindcss": "^3.4.19" (expected version in package.json)
+ "tailwindcss": "3.4.19" (installed version in node_modules)

Make sure to run pnpm install and try again.

​

Migration approaches

​

Automated upgrade (recommended)

npx @tailwindcss/upgrade

• Migrate CSS files from v3 syntax to v4
• Convert JavaScript config files to CSS @theme blocks
• Update all template files with renamed utilities
• Install the latest Tailwind CSS packages
• Update PostCSS configuration if needed

​

Manual upgrade

npm install tailwindcss@next @tailwindcss/postcss@next

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

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

​

What the upgrade changes

​

CSS files

• Converts @tailwind directives to @import "tailwindcss"
• Migrates @layer utilities to @utility syntax
• Converts @apply statements to use updated class names
• Adds @theme blocks with your customizations
• Updates @import statements to include layer() where needed

​

JavaScript configuration

• Converts tailwind.config.js to CSS @theme blocks
• Migrates theme customizations to CSS variables
• Converts custom variants to @custom-variant
• Handles plugin configurations
• Removes the config file if fully migrated

​

Template files

• Updates all renamed utility classes (see v3 to v4 guide)
• Migrates arbitrary values to named values where possible
• Updates variant syntax to v4 conventions
• Canonicalizes class names to their preferred form

​

Dependencies

• tailwindcss
• @tailwindcss/cli
• @tailwindcss/postcss
• @tailwindcss/vite
• prettier-plugin-tailwindcss

​

Common upgrade scenarios

​

Vite projects

1. Install @tailwindcss/vite
2. Update your Vite configuration
3. Remove PostCSS config if no longer needed
4. Update your CSS imports

// vite.config.js
import tailwindcss from '@tailwindcss/vite'

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

​

PostCSS projects

1. Updates to use @tailwindcss/postcss
2. Removes autoprefixer (now built-in)
3. Updates PostCSS configuration

​

Next.js projects

1. Updates CSS imports in your global stylesheet
2. Migrates configuration to CSS
3. Preserves Next.js-specific optimizations

​

Monorepo projects

1. Supports multiple config files
2. Handles workspace dependencies correctly
3. Updates all packages that use Tailwind CSS

​

Verification steps

npm run build

@theme {
  --color-*: initial; /* Your colors */
}

@media (prefers-color-scheme: dark) {
  @theme {
    --color-*: initial; /* Dark colors */
  }
}

​

Troubleshooting

​

Git directory not clean

# Commit your changes first
git add .
git commit -m "Prepare for Tailwind CSS v4 upgrade"

# Or use --force (not recommended)
npx @tailwindcss/upgrade --force

​

Version mismatch errors

# Ensure dependencies are installed
npm install

# Then try again
npx @tailwindcss/upgrade

​

Configuration not migrating

• Complex plugin configurations
• Custom variant functions
• Dynamic theme values

​

Class names not updating

1. Check if they’re in ignored files (node_modules, etc.)
2. Verify file extensions are recognized
3. Look for dynamic class generation that can’t be statically analyzed

​

Getting help

• Check the v3 to v4 Migration Guide for breaking changes
• Review the Codemods documentation for tool details
• Visit the GitHub Discussions
• Report bugs on GitHub Issues

​

Next steps

1. Review the CHANGELOG for new features
2. Explore new utilities like container queries and 3D transforms
3. Take advantage of CSS-first configuration for better IDE support
4. Consider using the Vite plugin for optimal performance