Why Tailwind v4 matters

Tailwind CSS v4 is a ground-up rewrite. Instead of a JavaScript config file driving everything, styling now lives closer to your CSS — with @import 'tailwindcss', @theme, and native cascade layers.

Tailwind v4 works with PostCSS, Vite, and frameworks like Next.js. You no longer need tailwind.config.js for most projects.

Project setup

In a Next.js project, your global stylesheet becomes the source of truth:

code
@import 'tailwindcss';
 
@theme {
  --font-sans: 'Rubik', system-ui, sans-serif;
  --color-brand: #7c3aed;
}

That's it — no separate content array. Tailwind scans your project automatically.

Custom utilities with @utility

v3 used @layer utilities and arbitrary values. v4 introduces @utility for first-class custom classes:

code
@utility text-gradient {
  background-image: linear-gradient(to right, #6ee7b7, #38bdf8);
  -webkit-background-clip: text;
  background-clip: text;
  color: transparent;
}

Use it anywhere in JSX:

code
<h1 className="text-gradient text-4xl font-bold">DevCo</h1>

@theme vs :root

Design tokens belong in @theme inline when you want Tailwind to generate matching utilities:

code
@theme inline {
  --color-surface: #1f2937;
  --color-accent: #7c3aed;
}

Now bg-surface, text-accent, and border-accent work out of the box.

Keep one-off CSS variables in :root when you don't need utility classes — for example, prose styles or third-party overrides.

Migration checklist

v3 patternv4 equivalent
tailwind.config.ts theme.extend@theme in CSS
@apply in component CSSStill works in @layer
plugins: []CSS-native features or @plugin
darkMode: 'class'Custom variant or single theme

Common gotchas

Unknown utility errors — If @apply text-gradient fails, register the utility with @utility before using it in @apply, or write the raw CSS instead.

Border colors — Global * { border-color } rules outside @layer base can override Tailwind border utilities. Keep resets inside @layer base.

Config file — You can still use @config "../tailwind.config.ts" for animations and legacy extensions while migrating gradually.

Conclusion

Tailwind v4 rewards a CSS-first mindset. Start with @import 'tailwindcss', move tokens into @theme, and promote repeated patterns to @utility. The result is less config noise and faster builds — especially in App Router projects where global CSS is already central.

Next steps

  1. Migrate your color palette to @theme inline
  2. Replace one-off @layer utilities blocks with @utility
  3. Remove unused plugins from your old config

Third-party UI libraries built for Tailwind v3 may need updates before they work with v4's engine.