Tailwind CSS v4 2026: Migration Best Practices

What Changed in Tailwind CSS v4

Tailwind CSS v4 introduces three architectural changes that affect every project upgrading from v3: a new engine built on a high-performance Rust core, a CSS-native configuration system replacing the JavaScript config file, and a class name canonicalisation pass that removes legacy aliases. Understanding what changed at the architecture level clarifies why the migration steps are what they are.

The Unified Toolchain Model

In Tailwind v3, the build pipeline required postcss, autoprefixer, and tailwindcss as separate packages wired together in a postcss.config.js. Tailwind v4 ships native integrations for Vite (@tailwindcss/vite) and PostCSS (@tailwindcss/postcss) that handle CSS processing, vendor prefixes, and Tailwind compilation in a single package. The PostCSS config simplifies to a single plugin entry.

// v3 — three separate packages
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// v4 — single package handles everything
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

For projects using Vite, the PostCSS config is no longer needed at all. Import the Vite plugin in vite.config.ts and add a single @import "tailwindcss" line in your global CSS file — that is the entire setup. Next.js projects (which use PostCSS) switch to the @tailwindcss/postcss package for a similarly streamlined configuration. For a deeper look at how this toolchain fits into modern Next.js architecture, see our Next.js 16 performance and server components guide.

Breaking Changes Checklist

Tailwind v4 removes all class aliases that did not match their underlying CSS property names. The table below covers every renamed utility you are likely to encounter in a real codebase. Classes not listed here are unchanged and work identically in v4.

Automated Migration with Codemods

The Tailwind team provides an official upgrade tool that automates the class renames, config file migration, and package updates. For most projects, running the codemod is the correct starting point — manual class hunting is error-prone and time-consuming when the tool handles it reliably.

Running the Upgrade Tool

# Run from your project root
npx @tailwindcss/upgrade

# For specific directories
npx @tailwindcss/upgrade --config ./tailwind.config.js

# Preview changes without writing files (dry run)
npx @tailwindcss/upgrade --dry-run

The upgrade tool performs the following operations automatically:

What the Codemod Cannot Handle

The upgrade tool handles class renames and straightforward configuration migration, but several scenarios require manual intervention:

CSS-Native Theme Configuration

The most architecturally significant change in Tailwind v4 is the elimination of the JavaScript config file for theme configuration. All design tokens — colours, spacing, typography, border radius, shadows — now live in a @theme block in your global CSS file. This is not merely a syntax change: it fundamentally changes how theme tokens are consumed in the browser.

From tailwind.config.js to @theme

// tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50:  "#eff6ff",
          500: "#3b82f6",
          900: "#1e3a8a",
        },
      },
      fontFamily: {
        sans: ["Geist", "system-ui", "sans-serif"],
      },
      borderRadius: {
        "4xl": "2rem",
      },
    },
  },
};

/* globals.css (v4) */
@import "tailwindcss";

@theme {
  --color-brand-50:  #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a8a;

  --font-sans: "Geist", system-ui, sans-serif;

  --radius-4xl: 2rem;
}

The key insight is that @theme variables are real CSS custom properties accessible throughout your stylesheet with var(--color-brand-500). You get the Tailwind utility classes (text-brand-500, bg-brand-50) and access to the raw CSS custom property in the same token — no duplication needed.

Runtime Theme Switching

Because theme tokens are CSS custom properties, runtime theme switching no longer requires a rebuild. Override the @theme variables at a selector level and every Tailwind utility using those tokens updates automatically:

@import "tailwindcss";

@theme {
  /* Default (light) theme */
  --color-surface: #ffffff;
  --color-surface-raised: #f4f4f5;
  --color-text-primary: #18181b;
  --color-accent: #3b82f6;
}

/* Dark theme — override tokens at selector level */
[data-theme="dark"] {
  --color-surface: #09090b;
  --color-surface-raised: #18181b;
  --color-text-primary: #fafafa;
  --color-accent: #60a5fa;
}

/* High contrast theme */
[data-theme="high-contrast"] {
  --color-surface: #000000;
  --color-text-primary: #ffffff;
  --color-accent: #ffff00;
}

Switching themes is a single attribute change on the <html> element: document.documentElement.dataset.theme = 'dark'. This replaces multi-config setups that previously required separate Tailwind builds or complex CSS-in-JS theming solutions. For projects building headless storefronts with complex theming requirements, see our headless CMS comparison for 2026.

New Utilities and Features

Beyond the migration work, Tailwind v4 ships a substantial set of new utilities that were not available in v3. These additions reduce reliance on arbitrary values and cover CSS features that have reached broad browser support in 2024-2026.

<div class="@container">
  <p class="@sm:text-lg @lg:text-2xl">
    Responsive to its container
  </p>
</div>

@theme {
  /* Wide-gamut custom color */
  --color-brand: oklch(0.6 0.2 250);
}

@utility tab-4 {
  tab-size: 4;
}

/* Usage: class="tab-4 hover:tab-4" */

<div class="perspective-800 rotate-y-12
            hover:rotate-y-0 transition-transform">
  Card with 3D effect
</div>

Additional new utilities in v4 include field-sizing-content for auto-resizing textareas, text-wrap-balance and text-wrap-pretty for typographic wrapping control, inset-shadow-* for inner shadow utilities, and not-* variants for CSS :not() selector support.

Performance Improvements

The performance story for Tailwind v4 is the most compelling reason to upgrade for teams working on large codebases. The new engine, built on a Rust core called Lightning CSS, replaces the Node.js-based PostCSS pipeline that had been the bottleneck for large projects running full Tailwind rebuilds.

The speed gains come from three sources. First, Lightning CSS processes CSS significantly faster than the Node.js PostCSS pipeline because Rust has dramatically lower per-operation overhead. Second, the v4 engine uses a smarter class scanning algorithm that only re-parses files that have changed since the last build rather than scanning the entire codebase on every hot-reload. Third, the unified toolchain eliminates the startup overhead of initialising multiple PostCSS plugins on each rebuild cycle.

Integration with Frameworks

Tailwind v4 ships first-party integrations for the most common JavaScript frameworks. The setup in each case is simpler than v3 because the unified toolchain handles what previously required manual PostCSS configuration.

# Install
npm install tailwindcss @tailwindcss/postcss

# postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

# globals.css
@import "tailwindcss";

@theme {
  --font-sans: var(--font-geist-sans), system-ui, sans-serif;
  --font-mono: var(--font-geist-mono), monospace;
}

# Install
npm install tailwindcss @tailwindcss/vite

// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";

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

/* main.css — single import replaces @tailwind directives */
@import "tailwindcss";

Design System Migration

For teams maintaining a design system — a shared set of tokens, components, and theme definitions used across multiple projects — the Tailwind v4 migration requires a planned approach rather than a run-the-codemod-and-ship workflow. The good news is that the CSS-native token system in v4 is a significantly better foundation for design systems than the JavaScript config approach in v3.

Token Architecture in v4

In v3, design tokens lived in tailwind.config.js and were consumed exclusively through Tailwind utilities. Any component that needed a token value in a CSS property outside Tailwind's utility coverage had to duplicate the value or use a workaround. In v4, every @theme token is a CSS custom property, making it universally available across Tailwind utilities, CSS Modules, and inline styles alike.

/* Shared across all apps in a monorepo */
@layer theme {
  @theme {
    /* Brand palette */
    --color-primary-50:  oklch(0.97 0.02 250);
    --color-primary-500: oklch(0.60 0.20 250);
    --color-primary-900: oklch(0.25 0.15 250);

    /* Semantic tokens */
    --color-surface:           var(--color-zinc-50);
    --color-surface-elevated:  #ffffff;
    --color-text-body:         var(--color-zinc-700);
    --color-text-heading:      var(--color-zinc-900);
    --color-border:            var(--color-zinc-200);

    /* Typography */
    --font-sans: "Inter", system-ui, sans-serif;
    --font-display: "Cal Sans", "Inter", sans-serif;

    /* Spacing scale additions */
    --spacing-18: 4.5rem;
    --spacing-22: 5.5rem;

    /* Border radius */
    --radius-pill: 9999px;
    --radius-card: 0.75rem;
  }
}

/* Dark theme overrides */
[data-theme="dark"] {
  --color-surface:          var(--color-zinc-950);
  --color-surface-elevated: var(--color-zinc-900);
  --color-text-body:        var(--color-zinc-300);
  --color-text-heading:     var(--color-zinc-50);
  --color-border:           var(--color-zinc-800);
}

Migration Checklist for Design Systems

Tailwind v4's CSS-native token system pairs exceptionally well with component-driven development workflows. Our web development services help teams establish scalable design systems and migrate existing codebases to modern toolchains without disrupting ongoing product development.