Migrating to Tailwind CSS v4: A Practical Guide

Tailwind CSS v4 is a complete rewrite under the hood. The most visible change: there's no tailwind.config.js anymore. Configuration happens directly in your CSS file using @theme.

What Changed

### Configuration moves into CSS


@import "tailwindcss";

@theme {
  --color-primary: #dc2626;
  --font-sans: "Inter", system-ui, sans-serif;
  --spacing-18: 4.5rem;
}

### New high-performance engine

Tailwind v4 uses a Rust-based engine called Oxide that's up to 10x faster for full builds and 100x faster for incremental builds.

### Simplified PostCSS config


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

Or with Vite:


import tailwindcss from "@tailwindcss/vite";
export default defineConfig({ plugins: [tailwindcss()] });

Migration Steps

1. Update packages — npm install tailwindcss@^4 @tailwindcss/vite 2. Replace your PostCSS config with the new format above 3. Move theme values from tailwind.config.js into CSS @theme {} blocks 4. Remove the config file — it's no longer needed for basic setups 5. Update custom utilities to use the new @utility directive

Breaking Changes to Watch For

theme() function syntax changed slightly in CSS

Some plugin APIs were updated

darkMode: 'class' is now @variant dark (&:is(.dark *))

Is it Worth Upgrading?

Absolutely. The build speed alone is worth it for large projects. The CSS-first config also feels more natural once you're used to it.

Our courses are already updated to teach Tailwind v4 from scratch.