Tailwind CSS v4 changes how you import it — the old PostCSS setup no longer works

Tailwind CSS v4 is a complete rewrite and the migration is not trivial.

The biggest immediate breaking change: the old @tailwind base/components/utilities directives are gone. The new import is a single line:

/* OLD — v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* NEW — v4 */
@import "tailwindcss";

But that is just the start. The tailwind.config.js file is also gone. All configuration now lives in your CSS file using @theme:

@import "tailwindcss";

@theme {
  --color-brand: #00E5A0;
  --font-display: "Syne", sans-serif;
  --breakpoint-3xl: 120rem;
}

What to do before upgrading:

• Run npx @tailwindcss/upgrade — it handles most of the migration automatically
• Check your postcss.config.js — v4 uses a new plugin: @tailwindcss/postcss
• Any custom plugins using the old API need to be rewritten

Do not upgrade mid-project without a dedicated migration window. The DX after migration is genuinely better but the path is rough.