Tailwind CSS v4: CSS-first configuration and a new engine

Released in January 2025, Tailwind CSS v4 is an almost complete rewrite. If you enjoyed v3 in my "Mastering Tailwind CSS" article, the philosophy is the same (utility classes), but configuration, engine and setup change deeply.

A much faster engine

The engine, called Oxide, was rewritten with performance-critical parts in Rust. According to the Tailwind team, full builds are up to 5x faster and incremental builds over 100x faster, often measured in microseconds. In practice, hot reload becomes instant even on large projects.

No more tailwind.config.js: configuration moves to CSS

This is the most visible change. Everything is now configured directly in your CSS file, with the @theme directive.

/* app/globals.css */
@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.62 0.19 259);
  --color-brand-600: oklch(0.55 0.2 262);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 120rem;
}

These variables automatically generate the matching utilities (bg-brand-500, font-display, 3xl:grid-cols-6) and remain available as native CSS variables anywhere in your code: var(--color-brand-500). No more duplicating colors between a JavaScript config and CSS.

Simpler setup

• One line: @import "tailwindcss"; replaces the three @tailwind base/components/utilities directives.
• Automatic source detection: no more listing files in content; Tailwind scans the project while respecting .gitignore. The @source directive adds a folder when needed.
• Dedicated plugins: @tailwindcss/vite for Vite, @tailwindcss/postcss for other tools (including Next.js). autoprefixer and postcss-import are no longer needed.

New features worth knowing

• Built-in container queries: @container on the parent, then @sm:grid-cols-2 on children, no plugin.
• An `oklch` palette: more vivid colors on P3 displays and smoother gradients.
• Dynamic values: grid-cols-15 or mt-17 work with no configuration; scales are derived from a --spacing variable.
• New variants: starting: for entry animations (@starting-style), not-*, inert, nth-*.
• Modern CSS under the hood: native cascade layers, @property and color-mix() for opacity.

Migrating from v3

Tailwind ships a tool that does most of the work: npx @tailwindcss/upgrade. It converts the JavaScript config to @theme, updates dependencies and renames changed classes. A few changes deserve a manual check:

• Renamed classes: shadow-sm becomes shadow-xs, shadow becomes shadow-sm, rounded becomes rounded-sm, outline-none becomes outline-hidden…
• Default border color is now currentColor: add an explicit color to your border classes.
• Browser support: v4 targets Safari 16.4+, Chrome 111+ and Firefox 128+. If you must support older browsers, stay on v3.
• A project with a large JS config can keep its file temporarily with @config "./tailwind.config.js";.

Conclusion

Tailwind v4 brings the tool closer to native CSS: configuration becomes CSS, design tokens become CSS variables and the engine all but disappears from build times. For a new project it is the obvious choice; for an existing one, migration is largely automated, as long as you check browser support.