Tailwind CSS v4: What Changed and How to Migrate

We run Tailwind CSS v4 on this site and on the BrokLeads web app. It isn't just a version bump: the configuration model is different. Here's what changed and how to migrate without breaking your existing set-up.

The Biggest Change: CSS-First Configuration

Tailwind v4 eliminates tailwind.config.js. Your configuration now lives directly in CSS:

/* In your main CSS file */
@import "tailwindcss";

@theme {
  --color-brand: #009688;
  --color-brand-dark: #007A6B;
  --color-accent: #FF6B35;
  --font-sans: "Inter", sans-serif;
  --radius-card: 1rem;
}

That's it. No JavaScript config file, no content array to maintain, no theme.extend object. The @theme directive registers CSS custom properties as design tokens, and Tailwind automatically generates utility classes from them.

So if you define --color-brand: #009688, you automatically get bg-brand, text-brand, border-brand, ring-brand, and all their opacity variants. It clicks once you see it in action, and it's genuinely elegant.

Performance

The engine was rewritten for speed. Tailwind's team reports full builds up to 5x faster and incremental builds over 100x faster than v3 in the v4.0 announcement. You'll notice it most in watch mode, where rebuilds feel instant.

The new engine also handles modern CSS features itself, so you need fewer PostCSS plugins.

The @import Change

Previously, you had three @tailwind directives at the top of your CSS:

/* v3 — old way */
@tailwind base;
@tailwind components;
@tailwind utilities;

In v4, it's a single import:

/* v4 — new way */
@import "tailwindcss";

With Vite, use the @tailwindcss/vite plugin. With Next.js, use @tailwindcss/postcss: this site's whole PostCSS config is that one plugin.

Content Detection Is Now Automatic

In v3, you had to specify which files Tailwind should scan:

// v3 tailwind.config.js
content: ["./src/**/*.{js,ts,jsx,tsx}"]

In v4, this is automatic. Tailwind scans your project files without configuration. This eliminates a common source of confusion ("why isn't my class being generated?") that happened when someone forgot to add a new directory to the content array.

Arbitrary Values Still Work

Good news: arbitrary values like bg-[#FF6B35], w-[calc(100%-2rem)], and text-[clamp(1rem,5vw,3rem)] work exactly the same. If you've been relying on arbitrary values heavily, nothing breaks here.

What to Watch For

The config migration is the main friction point. Custom colours, fonts and spacing in tailwind.config.js move to @theme blocks in CSS. Tailwind ships an upgrade tool (npx @tailwindcss/upgrade) that does most of this for you. It's quick on a small project; for a large design system, plan for longer and review the diff.

Some third-party component libraries that ship their own Tailwind config had compatibility issues during the initial v4 release window. Most have since published v4-compatible versions. Check your dependencies before upgrading.

Step-by-Step Migration

1. Update packages: npm install tailwindcss@latest @tailwindcss/postcss@latest
2. Replace the three @tailwind directives with @import "tailwindcss"
3. Move all theme values from tailwind.config.js into an @theme {} block in your CSS file
4. Delete tailwind.config.js (or keep it empty if a plugin requires it)
5. Remove the content array configuration — no longer needed
6. Update your PostCSS config to use @tailwindcss/postcss instead of tailwindcss
7. Run a build and check the output — class generation issues will surface immediately

Should You Upgrade Now?

For new projects: yes, start with v4 from day one. The CSS-first config is cleaner to maintain, and you get the performance improvements for free.

For existing v3 projects there's no emergency, but v4 is where new features land, so plan the upgrade rather than postponing it forever. Check the browser support notes first (v4 targets modern browsers), and compare screenshots of key pages before and after to catch rendering differences.

Planning the upgrade as part of a bigger rebuild? Here's how we approach web development projects, from the first audit to launch.