Alex Chen — Software Engineer

Tailwind v4 is a significant rewrite. The approach to configuration, theming, and the build pipeline have all changed. Here's what I learned migrating a medium-sized project (around 120 components) from v3 to v4.

The Big Change: CSS-First Configuration

In v3, your theme lived in tailwind.config.js. In v4, it lives in your CSS file.

/* v4 — configure directly in CSS */
@import "tailwindcss";

@theme {
  --color-brand: oklch(55% 0.2 240);
  --font-sans: "Inter", sans-serif;
  --radius-lg: 0.75rem;
}

This feels odd at first, but it's actually cleaner. Your design tokens are co-located with your styles, and you get native CSS custom properties without any plugin gymnastics.

The Build Pipeline

Tailwind v4 uses a new Rust-based engine (Oxide) that's substantially faster. On the project I migrated, cold build times dropped from ~4.2s to ~0.8s. Incremental builds are nearly instant.

The PostCSS plugin still works, but if you're using Vite, the dedicated @tailwindcss/vite plugin is the right choice.

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

export default {
  plugins: [tailwindcss()]
}

Breaking Changes to Know

Utility renames. Several utilities were renamed for consistency. The migration guide covers the full list, but the ones I hit most often:

shadow → shadow-sm (the default shadow is now slightly smaller)
ring width defaults changed slightly

@apply behavior. Some @apply patterns that worked in v3 are stricter in v4. If you have a lot of @apply in your component styles, test carefully.

JIT is now the only mode. There's no more "just-in-time" vs "AOT" distinction — v4 is always JIT.

What I Actually Like

The CSS custom properties approach makes runtime theming trivial. Dark mode, user-adjustable font sizes, and brand color switching all work without JavaScript hacks.

The new oklch color space support is excellent. Colors defined in oklch perceptually interpolate better, which makes hover states and gradients look significantly more polished.

Verdict

The migration is worth it for most projects. Budget a day for a medium-size codebase, write tests for your critical UI paths first, and lean on the official migration guide for the mechanical changes. The speed and improved CSS primitives pay dividends quickly.