Tailwind CSS v4: what's new and what's changed
Tailwind v4 is a significant rewrite. Here's what's changed, what's better, and what you need to know before upgrading.
Have you upgraded yet? Tailwind CSS v4 has reached stable release after a long beta, and it's a bigger change than a typical major version bump. The core has been rewritten as a Rust-based engine called Oxide, the configuration system has been overhauled, and the CSS-first approach replaces much of what used to live in tailwind.config.js. I've been using it on new projects for a few months now, so here's a practical assessment.
The headline changes
The most visible change is that configuration has moved from JavaScript to CSS. Instead of a tailwind.config.js file defining your theme, you define custom values directly in your CSS using the @theme directive. Colours, spacing, fonts, breakpoints, all defined in CSS custom properties. This feels more natural, since you're configuring a CSS framework in CSS rather than JavaScript, and it means your editor's CSS tooling works with your custom values.
The new engine is significantly faster. Build times on my larger projects dropped from around 300ms to under 50ms. For development, this means hot reloads are essentially instant. For production builds, the difference is less noticeable (builds were already fast enough), but it matters for CI pipelines.
Automatic content detection replaces the content array in your config. Tailwind v4 automatically finds your template files based on your project structure, which eliminates a common source of "why aren't my classes working" issues. You can still configure it manually if you need to, but the defaults work for standard Next.js, Vite, and other common setups.
What's better
The CSS-first configuration genuinely improves the development experience. In v3, if you wanted to reference your theme values in custom CSS, you needed the theme() function. In v4, your theme values are CSS custom properties, so you use them with standard var() syntax. This makes mixing Tailwind utility classes with custom CSS much more natural.
Container queries are now supported natively with the @container variant. This has been possible via a plugin in v3, but having it built in with a clean syntax (@container/sidebar) makes component-level responsive design practical rather than awkward.
The new colour system uses OKLCH by default, which provides more perceptually uniform colour manipulation. The practical benefit: when you use opacity modifiers (like bg-blue-500/50), the result looks better because OKLCH handles alpha compositing more naturally than sRGB.
What to watch out for
The migration from v3 isn't trivial. The config format change means you need to translate your tailwind.config.js into CSS @theme directives. The team has published a migration guide and an upgrade tool, but I found that projects with heavily customised configs needed manual work. Custom plugins that rely on the JavaScript API may need significant refactoring.
Some utility names have changed for consistency. The divide utilities have been restructured, some spacing scale values have shifted, and there are new naming conventions for certain variants. The upgrade tool catches most of these, but review your output carefully.
If you're using Tailwind with a component library that generates class names dynamically, test thoroughly. The new content detection is smart but it can miss dynamically constructed class names (the same issue that existed in v3, but the detection mechanism is different).
Should you upgrade?
New projects: absolutely use v4. The improvements are substantial and the API is cleaner. Existing v3 projects: upgrade when you have time to do it properly, not as a drive-by change. Plan a dedicated branch, run the upgrade tool, review the output, test everything, and merge. There's no urgency, v3 isn't going anywhere immediately, and a botched migration is worse than waiting.
If you're planning a new build or considering upgrading an existing Tailwind project, I'm happy to help, get in touch.
Chris Ryan
Managing Director
17+ years in full-stack web development, most of it leading teams agency-side across e-commerce, CMS platforms, and bespoke applications. Specialises in infrastructure, system integration, and data privacy, with hands-on experience as a Data Protection Officer. Founded Innatus Digital in 2020 to offer the kind of honest, technically-led partnership that he felt was missing from the agency world.