Skip to content

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.

11 min read
Conceptual modular facade with interchangeable teal panels and a flowing translucent ribbon.
On this page

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.

What actually changed in Tailwind CSS v4

Four changes touch nearly every real codebase. None of them is hard on its own; the work is in finding every place they apply.

Configuration moved into your CSS

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.

js
// v3: tailwind.config.js
module.exports = {
  content: ["./src/**/*.{html,js,ts,tsx}"],
  theme: {
    extend: {
      colors: { brand: { 500: "#16a34a" } },
    },
  },
  plugins: [require("@tailwindcss/typography")],
};
css
/* v3: src/app.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
css
/* v4: src/app.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

@theme {
  --color-brand-500: oklch(0.62 0.17 145);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 120rem;
}

@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]

Where configuration lives Tailwind v3 tailwind.config.js content: ["./src/**/*.{ts,tsx}"] theme: { extend: { colors } } plugins, safelist, corePlugins app.css @tailwind base / components / utilities Tailwind v4 app.css @import "tailwindcss"; @source "../node_modules/@acme/ui"; @theme { --color-brand-500: ... } @plugin "@tailwindcss/typography"; @config: optional JS bridge Tokens become utilities and CSS vars
Figure 1. Configuration moves from a JavaScript file plus directives into one stylesheet, with @config available as a temporary bridge.

Content detection is automatic

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.

css
@import "tailwindcss";
@source "../node_modules/@acme/ui";
ts
// Invisible to the scanner: the full class name is never written out here
export const badTone = (tone: "red" | "green") => `text-${tone}-600`;

// Visible: every class name exists as a complete string
const 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.

One package per build tool

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]

js
// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
ts
// vite.config.ts
import { 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]

Defaults and class names shifted

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.

bash
git switch -c chore/tailwind-v4
npx @tailwindcss/upgrade

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.

A five-phase Tailwind CSS v4 upgrade plan

I'd run this as phases with exit criteria, not as a timebox. Each phase ends with something a reviewer can check.

Five phases, each with an exit criterion Phase 1 Inventory Exit: one list with owners Phase 2 Browser call Exit: recorded decision Phase 3 Codemod on a branch Exit: branch builds Phase 4 Visual and behavior diff Exit: every diff fixed or accepted Phase 5 Ship and remove bridge Exit: no @config left in the repo
Figure 2. Each phase ends with something a reviewer can check, and the browser call comes before any code changes.

Phase 1: Inventory

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 v4
grep -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.

Phase 2: Make the browser call

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".

Phase 3: Codemod on a branch

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.

Phase 4: Visual and behavior diff

Screenshot diffs catch the scale renames and color changes. They don't catch behavior. Check these by hand on the pages that matter most:

  • Hover-only interactions on a touch device, since hover now needs a hover-capable input
  • Buttons that relied on Preflight's old cursor: pointer
  • Elements with the hidden attribute plus a display class
  • Lists using space-y-* or divide-y-*, whose selectors changed for performance
  • Stacked variants where order matters, such as first:*:pt-0, which becomes *:first:pt-0
  • Focus styles that used bare ring or outline-none

Exit criterion: every difference is either fixed or accepted on purpose.

Phase 5: Ship and remove the bridge

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.

Key takeaways

  • 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.

Sources

  1. [1]Theme variables · Tailwind CSS docs
  2. [2]Functions and directives · Tailwind CSS docs
  3. [3]Detecting classes in source files · Tailwind CSS docs
  4. [4]Upgrade guide · Tailwind CSS docs
  5. [5]Tailwind CSS v4.0 · Tailwind Labs
  6. [6]Compatibility · Tailwind CSS docs
  7. [7]Tailwind CSS v4.1: Text shadows, masks, and tons more · Tailwind Labs

Checked against these sources on

Related Articles