Do I need to remove tailwind.config.js when upgrading to v4?

Yes, eventually. Tailwind v4 no longer automatically reads tailwind.config.js. The upgrade codemod (npx @tailwindcss/upgrade) will migrate your config to the new @theme CSS-first format automatically.

Is Tailwind CSS v4 compatible with older browsers?

Tailwind v4 targets the same browser support as v3 (modern browsers, generally >95% global coverage). Lightning CSS handles the transformation of modern CSS features like OKLCH colors, logical properties, and nesting to formats that older browsers understand.

Can I still use CSS-in-JS libraries with Tailwind v4?

Yes, and the experience is actually better in v4. Because design tokens are now proper CSS custom properties defined in @theme, you can reference them in CSS-in-JS as regular CSS variables (var(--color-brand-500)) without any special integration.

Tailwind CSS v4: Everything That Changed and How to Migrate (2026 Guide)

TL;DR

Comprehensive Tailwind CSS v4 migration guide: Lightning CSS engine (5x faster), CSS-first @theme config, new color system, breaking changes (border defaults, r

Tailwind CSS v4 landed in early 2025 and immediately broke a significant portion of existing projects. Not because the Tailwind team made careless decisions — they made deliberate, ambitious ones. The result is a framework that is faster, more capable, and architecturally cleaner than v3. But getting there requires understanding what changed and why.

This guide covers every significant change in Tailwind CSS v4, with before-and-after code examples for each breaking change, migration strategies, and performance benchmarks. Whether you’re upgrading an existing project or starting fresh, here’s what you need to know.

The Lightning CSS Engine: 5x Faster Rebuilds

The most immediately noticeable change in Tailwind v4 is speed. Tailwind has replaced its PostCSS-based compilation pipeline with Lightning CSS — a Rust-based CSS parser, transformer, and minifier that processes CSS significantly faster than JavaScript-based alternatives.

Benchmark Numbers

Project Size	Tailwind v3 Build	Tailwind v4 Build	Improvement
Small (50 components)	420ms	82ms	5.1x faster
Medium (200 components)	1,840ms	340ms	5.4x faster
Large (800+ components)	7,200ms	1,310ms	5.5x faster

For incremental rebuilds (hot module replacement during development), the numbers are even more dramatic. Tailwind v4 achieves sub-50ms incremental rebuilds on most projects, making the development feedback loop feel nearly instantaneous.

What Lightning CSS Adds Beyond Speed

Lightning CSS is not just a faster PostCSS replacement. It adds native support for:

CSS nesting — native nesting transforms (no more plugins)
Logical properties — transforms for older browsers
Color function normalization — oklch, color-mix, and other modern color functions work across browsers
Vendor prefixing — automatic where still needed

PostCSS is still supported in v4 as a plugin mode for compatibility, but Lightning CSS is the default and recommended engine.

CSS-First Configuration: The @theme Directive

This is the most architecturally significant change in Tailwind v4. The tailwind.config.js file is gone. Configuration now lives in your CSS file using the @theme directive.

v3 Configuration (Before)

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a5f',
        }
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        display: ['Playfair Display', 'serif'],
      },
      spacing: {
        '18': '4.5rem',
        '88': '22rem',
      }
    }
  }
}

v4 Configuration (After)

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

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

  --font-family-sans: Inter, system-ui, sans-serif;
  --font-family-display: "Playfair Display", serif;

  --spacing-18: 4.5rem;
  --spacing-88: 22rem;
}

The @theme directive maps directly to CSS custom properties following a predictable naming convention. Every design token defined in @theme is automatically available as a Tailwind utility class AND as a CSS variable in your stylesheets.

Why This Is Better

CSS variables are native. Your design tokens are available everywhere CSS variables work — not just in utility classes, but in inline styles, CSS-in-JS, third-party components, and browser DevTools.
No more JavaScript parsing. The old config file required Node.js to parse and process. The CSS-first approach is just CSS.
Theme values update at runtime. Because tokens are CSS variables, you can override them with media queries, container queries, or JavaScript without rebuilding.
Better IDE integration. CSS-native tokens work with CSS variable autocomplete in any editor.

Importing the Config in Multiple Files

If you have a design system used across multiple CSS entry points, you can extract the theme to a shared file:

/* design-tokens.css */
@theme {
  --color-brand-500: #3b82f6;
  /* ... */
}

/* app.css */
@import "./design-tokens.css";
@import "tailwindcss";

Metric	Tailwind v3	Tailwind v4
Initial build	7.2s (large project)	1.3s (large project)
Incremental rebuild	340ms	44ms
CSS output size	28KB gzipped	21KB gzipped
CSS variable count	~180	~420 (more expressive)

The Lightning CSS Engine: 5x Faster Rebuilds

Benchmark Numbers

What Lightning CSS Adds Beyond Speed

CSS-First Configuration: The @theme Directive

v3 Configuration (Before)

v4 Configuration (After)

Why This Is Better

Importing the Config in Multiple Files

Try Our Free Tools

JSON Formatter & Validator

GST Calculator

More from developer-guides

Next.js 16 Just Dropped — 6 Changes That Break Everything You Know

New Color System

OKLCH: Why It Matters

Color Palette Changes

Composable Variants

What Composable Variants Enable

New Built-in Variants in v4

Breaking Changes from v3

1. Opacity Utilities

2. Border Defaults Changed

3. Ring Width Default Changed

4. Shadow Colors Are Now Transparent by Default

5. PostCSS Plugin Import Changed

6. Configuration File Removal

Migration: Using @tailwindcss/upgrade

Migration Checklist

Performance Benchmarks: v3 vs v4 in Production

People Also Ask

Do I need to remove tailwind.config.js when upgrading to v4?

Is Tailwind CSS v4 compatible with older browsers?

Can I still use CSS-in-JS libraries with Tailwind v4?

Should You Upgrade Now?

Ready to ship faster?

One insight, every Monday. 7am IST. Zero fluff.

Comments · 0

Key takeaways · 6

Topics

Article stats

Meta Tags & OG Preview

SIP & EMI Calculator