Tailwind CSS v4: What Changed and How to Plan the Upgrade
Tailwind CSS v4 moves config into CSS, renames utilities and raises the browser baseline. Here's what breaks and a five-phase plan to upgrade as bounded debt work.
Tailwind CSS v4 stopped reading the file most teams treat as their design system. tailwind.config.js is no longer detected automatically, the three @tailwind directives are replaced by one @import, and some of the most common class names in any v3 codebase, like shadow-sm, rounded and ring, now render differently.
None of that is hard to fix. The official upgrade tool rewrites most of it in one command. The risk is scope. An unplanned framework upgrade is how a quick dependency bump turns into a sprawling branch nobody wants to review, and a design regression someone finds after release.
Version 4.0 shipped on January 22, 2025 as a ground-up rewrite with a new engine, and the docs are now on the 4.3 line. If you're still on v3.4, you're carrying a known, bounded piece of technical debt. Here's what changed, the one decision that matters more than the syntax, and a five-phase plan for paying it down on purpose.
In v3, configuration lived in JavaScript and your stylesheet pulled in three layers with directives. In v4 it lives in CSS: one @import plus an @theme block. Every token you declare in @theme becomes a utility class and a native CSS custom property you can read at runtime.
@theme isn't :root with a new name. Theme variables tell Tailwind which utilities to generate, so --breakpoint-3xl above creates a 3xl: variant, and they must sit at the top level, not nested under selectors or media queries. Plain CSS variables that shouldn't produce classes still belong in :root.[1]
If you can't move everything on day one, @config loads a legacy JavaScript config explicitly, and @plugin loads JavaScript plugins. Three config options don't survive: corePlugins, safelist and separator. Safelisting moves to @source inline().[2]
Figure 1. Configuration moves from a JavaScript file plus directives into one stylesheet, with @config available as a temporary bridge.
There's no content array anymore. Tailwind scans your project as plain text and skips files in .gitignore, the node_modules directory, binary files, CSS files and lock files.[3]
Two consequences matter in a real repo. First, a component library installed as a package sits in node_modules, so it's invisible unless you register it with @source. Second, the scanner can't read string interpolation, so a class name assembled at runtime never gets generated. That was true in v3 too, but a safelist entry often hid it. With safelist gone from the config, those gaps can surface.
// Invisible to the scanner: the full class name is never written out hereexport const badTone = (tone: "red" | "green") => `text-${tone}-600`;// Visible: every class name exists as a complete stringconst toneClass = { red: "text-red-600", green: "text-green-600" } as const;export const goodTone = (tone: keyof typeof toneClass) => toneClass[tone];
In a monorepo where builds run from the root, @import "tailwindcss" source("../src"); sets the base path for scanning, and @source not excludes folders you don't want scanned.
In v3 the tailwindcss package was itself the PostCSS plugin. In v4 the integrations are separate packages: @tailwindcss/postcss, @tailwindcss/vite and @tailwindcss/cli. Imports and vendor prefixing are handled for you, so postcss-import and autoprefixer can come out of your dependencies.[4]
// vite.config.tsimport { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({ plugins: [tailwindcss()],});
The release post reports faster builds on Tailwind's own Catalyst benchmark: a full build went from 378ms to 100ms, and an incremental rebuild with no new CSS went from 35ms to 192µs. Nice, but I wouldn't use speed to justify the upgrade. If your CSS build is the bottleneck in your pipeline, you have a different problem.[5]
The quiet changes cause the most damage because nothing fails. A v3 shadow-sm still compiles in v4. It just renders a smaller shadow, because the scale moved down a step.
v3 class
v4 equivalent
shadow-sm / shadow
shadow-xs / shadow-sm
rounded-sm / rounded
rounded-xs / rounded-sm
blur-sm / blur
blur-xs / blur-sm
drop-shadow-sm / drop-shadow
drop-shadow-xs / drop-shadow-sm
outline-none
outline-hidden
ring (3px)
ring-3
bg-opacity-50
bg-black/50 (opacity modifier)
flex-grow / flex-shrink
grow / shrink
Defaults moved too. Border and divide colors now default to currentColor instead of gray-200. The bare ring is 1px and currentColor instead of 3px and blue-500. Placeholders use the current text color at 50% opacity, and buttons get cursor: default. The hover variant only applies on devices whose primary input supports hover. Stacked variants now apply left to right. And block or flex no longer override the hidden attribute.
One more: v4 isn't designed to work with Sass, Less or Stylus. Tailwind now handles imports, nesting and variables itself, so a Sass-heavy codebase has a bigger job than the rename table suggests.
# The browser baseline is the real Tailwind v4 decision
Most upgrade write-ups spend their time on syntax. I think that's backwards. Syntax is a codemod's job. The decision only an engineering lead can make is which browsers you're willing to stop treating as first-class.
The compatibility docs say v4 is designed for and tested on Safari 16.4, Chrome 111 and Firefox 128. Chrome 111 and Safari 16.4 shipped in March 2023, Firefox 128 in July 2024. The upgrade guide explains why: core framework features depend on modern CSS like @property and color-mix(). It's also blunt about the alternative: if you need to support older browsers, stay on v3.4 until your requirements change.[6]
Version 4.1 softened the edges. It added fallbacks so oklab colors, shadows and other @property-based features render in older Safari and Firefox. The release post still describes the framework as designed for Safari 16.4 and up, and says older browsers get a site that renders and stays usable, even if a few details differ.
So the real question isn't "can we run the codemod?" It's "what share of our users would get a degraded experience, and does product agree that's acceptable?" Pull the browser-version breakdown from your analytics before anyone touches the branch.[7]
Your situation
My default
Internal tools, admin panels, B2B apps on managed laptops
Upgrade. The baseline is rarely an issue.
Public product, analytics show little traffic below the baseline
Upgrade, and test one older Safari device by hand.
Meaningful traffic on old iPhones or iPads stuck below Safari 16.4
Get a written product decision first, or stay on v3.4.
Contractual browser support matrix that names older versions
Stay on v3.4 until the contract changes.
# What the Tailwind upgrade tool does and doesn't do
The official tool needs Node.js 20 or higher. The docs recommend running it on a new branch, then reviewing the diff and testing in the browser. They describe it as automating dependency updates, migrating your config file to CSS and handling changes in your template files.
Here's what it can't do. It can't decide whether you want v3 visuals preserved or v4 defaults adopted. It can't see a class name you assemble at runtime. It can't tell you whether a hover-only menu still works on a tablet. Those are judgment calls, and they're where the upgrade budget goes.
Before touching dependencies, count what you're migrating. This pipeline is a rough inventory, not a parser, but it tells you how many templates carry classes whose meaning changes:
bash
# Count v3 class names that were renamed, removed or changed in v4grep -rhoE --include='*.tsx' --include='*.ts' --include='*.html' \ '[a-z0-9:-]*(shadow|rounded|blur|ring|outline-none|flex-grow|flex-shrink|overflow-ellipsis|opacity)[a-z0-9-]*' src \ | sed 's/.*://' \ | grep -xE 'shadow(-sm)?|drop-shadow(-sm)?|blur(-sm)?|backdrop-blur(-sm)?|rounded(-sm)?|ring|outline-none|flex-(grow|shrink)(-0)?|overflow-ellipsis|(bg|text|border|divide|ring|placeholder)-opacity-[0-9]+' \ | sort | uniq -c | sort -rn
Then list the things no codemod handles well: JavaScript config options that no longer exist (corePlugins, safelist, separator), custom plugins, Sass or Less files, CSS modules and Vue or Svelte <style> blocks that use @apply (they need @reference), calls to resolveConfig, and dynamically built class names. Exit criterion: one list, with an owner for each item.
Take the analytics numbers to product and get the baseline decision in writing. Exit criterion: a recorded decision, either "Safari 16.4, Chrome 111, Firefox 128 and up are first-class" or "we stay on v3.4 until a named date or condition".
Run the upgrade tool on its own branch and commit its output untouched, so reviewers can separate machine changes from human ones. If you want the first release to look identical to v3, the upgrade guide documents compatibility CSS for the border and ring defaults. I treat that block as temporary debt with its own removal ticket.
css
@import "tailwindcss";@config "../tailwind.config.js";/* Temporary: keep v3 border and ring defaults until the visual review is done */@layer base { *, ::after, ::before, ::backdrop, ::file-selector-button { border-color: var(--color-gray-200, currentColor); }}@theme { --default-ring-width: 3px; --default-ring-color: var(--color-blue-500);}
Exit criterion: the branch builds, and every remaining v3 pattern from the Phase 1 list is either converted or ticketed.
Ship behind your normal release process. Then pay off the bridge: set border and ring colors explicitly where you want them, delete the compatibility block, and move the remaining JavaScript config into @theme so @config can go. Exit criterion: no @config line and no compatibility CSS left in the repo.
# Why a Tailwind upgrade belongs in your debt budget
A framework upgrade with a known end state is about the cleanest debt item you'll ever schedule. The scope is documented, the tooling exists, and the exit criteria are binary. If you score debt with a quadrant model, it's worth working out where it sits on the technical debt quadrant before arguing about priority.
Give it a slot in a planned technical debt sprint rather than squeezing it into feature work. And notice what it isn't: this is a mechanical migration, not a rewrite. If someone proposes redesigning the component library at the same time, that's a separate decision, and the refactor vs. rewrite call deserves its own discussion.
The cost of waiting is real but slow. Every new component written against v3 classes adds to the Phase 1 list. That's not a crisis. It's interest.
Tailwind CSS v4 moves configuration into CSS with @theme, detects content automatically and splits the build into separate PostCSS, Vite and CLI packages.
The dangerous changes are silent: renamed scales, new border and ring defaults, and hover behavior on touch devices.
The browser baseline (Safari 16.4, Chrome 111, Firefox 128) is the decision that needs a lead and a product owner, not the syntax.
Run the official upgrade tool on its own branch, then review visuals and behavior separately.
Treat compatibility CSS and @config as temporary debt with a removal ticket.
Make the browser call first. Everything after that is a checklist.
Frequently asked questions
Is Tailwind CSS v4 backward compatible with v3?
Not as a drop-in. A JavaScript config is no longer detected automatically (load it with @config), the @tailwind directives are replaced by @import "tailwindcss", and several utilities and defaults changed. The official upgrade tool handles most of the mechanical changes, but you still need to review the visual and behavior differences yourself.
Do I still need tailwind.config.js in Tailwind v4?
No. Design tokens go in an @theme block in your CSS. You can keep a JavaScript config during the migration by loading it with @config, but corePlugins, safelist and separator are not supported, and safelisting moves to @source inline(). Plan to move the rest into @theme and delete the file.
Can I use Tailwind CSS v4 with Sass or Less?
Tailwind v4 isn't designed to work with Sass, Less or Stylus. It handles imports, nesting and CSS variables itself, so the docs suggest treating Tailwind as your preprocessor. A codebase with a lot of Sass should plan that conversion as its own work item before or alongside the upgrade.
When should I stay on Tailwind CSS v3.4?
Stay on v3.4 if you must fully support browsers older than Safari 16.4, Chrome 111 or Firefox 128, for example under a contractual support matrix. Version 4.1 added fallbacks so older browsers still render a usable site, but the framework is still designed for that modern baseline and some details can differ.
My first big rewrite cost $400K and failed. The next three modernizations succeeded using a 6-phase strangler fig roadmap. Here's the complete playbook with real budget numbers.
Recognise a technical debt death spiral through delivery friction, recurring incidents and lost context, then stabilise one area and measure a focused recovery.
Compare technical debt practices from Netflix, Google and Stripe, including service ownership, code review, large-scale changes, typing and API versioning.
I replaced 183 Jira debt tickets with a 14-item Technical Debt Register and resolved 6 items in one quarter. Here's exactly what to track and what to skip.
Examine technical debt and developer turnover with frustration surveys, exit interviews, knowledge capture and improvement plans, while testing causal claims.
Plan a technical debt sprint around a baseline, a small set of focused changes and matched before-and-after measures so the team can show what improved.