Migrating from Tailwind CSS v3 to v4

Tailwind CSS v4 introduces a revolutionary architecture with significant performance improvements and a new CSS-first configuration approach. This guide documents the migration process from v3.4.1 to v4.0.

Why Migrate?

Performance Gains

Key Improvements

• CSS-first configuration: No more JavaScript config files
• Simplified imports: Single @import "tailwindcss" replaces three directives
• Modern architecture: Built for Safari 16.4+, Chrome 111+, Firefox 128+
• Better developer experience: Faster feedback loop during development

Migration Process

Automated Migration Tool

The easiest way to migrate is using the official upgrade tool:

1npx @tailwindcss/upgrade@latest

What the Tool Handles

The automated migration tool handles most of the heavy lifting:

1. Dependencies: Updates package.json with latest Tailwind v4
2. CSS imports: Converts @tailwind directives to @import
3. Configuration: Migrates JavaScript config to CSS variables
4. PostCSS: Updates PostCSS configuration

Before and After

CSS Imports Migration

Before (v3):

1@tailwind base;
2@tailwind components;
3@tailwind utilities;

After (v4):

1@import "tailwindcss";

Configuration Migration

Before (v3) - tailwind.config.ts:

1const config: Config = {
2  theme: {
3    extend: {
4      colors: {
5        primary: "#604d53",
6      },
7      screens: {
8        lg: "1336px",
9      },
10    },
11  },
12};

After (v4) - Inside CSS:

1@theme {
2  --color-primary: #604d53;
3  --breakpoint-lg: 1336px;
4}

PostCSS Configuration

Before (v3):

1const config = {
2  plugins: {
3    tailwindcss: {},
4  },
5};

After (v4):

1const config = {
2  plugins: {
3    "@tailwindcss/postcss": {},
4  },
5};

Custom Theme Migration

One of the most complex parts of migration involves custom themes. Here's how extensive custom color palettes are handled:

Color Palette Conversion

Before (v3):

1colors: {
2  wenge: {
3    DEFAULT: "#604d53",
4    100: "#130f11",
5    200: "#261f21",
6    // ... more shades
7  }
8}

After (v4):

1@theme {
2  --color-wenge: #604d53;
3  --color-wenge-100: #130f11;
4  --color-wenge-200: #261f21;
5  /* ... more shades */
6}

Breakpoint Migration

Custom breakpoints are automatically converted:

Before (v3):

1screens: {
2  sm: "480px",
3  fh: "1920px", // Full HD
4}

After (v4):

1@theme {
2  --breakpoint-sm: 480px;
3  --breakpoint-fh: 1920px;
4}

Custom Utilities

Utility classes using @layer need updating:

Before (v3):

1@layer utilities {
2  .global-spacing {
3    @apply px-4 py-4;
4  }
5}

After (v4):

1@utility global-spacing {
2  @apply px-4 py-4;
3}

Browser Compatibility

Supported browsers:

• Safari 16.4+
• Chrome 111+
• Firefox 128+

If you need to support older browsers, stick with v3.4 until your requirements change.

Potential Issues

Border Color Changes

v4 changes the default border color to currentcolor. The migration tool adds compatibility styles:

1@layer base {
2  *,
3  ::after,
4  ::before {
5    border-color: var(--color-gray-200, currentcolor);
6  }
7}

CSS Preprocessor Compatibility

Testing After Migration

After migration, thoroughly test:

1. Development server: Ensure yarn dev starts without errors
2. Build process: Verify yarn build completes successfully
3. Visual testing: Check all pages for layout regressions
4. Custom utilities: Verify all custom classes still work
5. Performance: Measure build time improvements

Results

After successful migration, you should see:

• Dramatically faster builds: Especially noticeable in development
• Cleaner configuration: CSS-based theme configuration
• Simplified setup: Single import statement
• Future-ready codebase: Built on modern web standards

The migration to Tailwind CSS v4 represents a significant architectural shift that delivers substantial performance benefits while maintaining the utility-first approach that makes Tailwind powerful.