Confession: I put off the v4 upgrade for four months. Not because v4 looked bad. I read the announcement post the day it dropped. It was because I had a Next.js app in production that leaned on maybe fifteen Tailwind plugins, half of which hadn’t been touched since 2023. I told myself I’d wait for “the ecosystem to catch up,” which is the excuse I use for every framework upgrade I don’t want to do.<\/p>\n
Then last weekend I finally sat down and did it. Two projects, a lot of coffee, roughly one Saturday. Most of it went fine. But there were about six things that quietly broke in ways the upgrade tool didn’t catch, and I want to write those down before I forget them.<\/p>\n
If you’re still on v3 and eyeing the official upgrade guide<\/a>, treat this as the sidecar post: what actually bit me, in the order it bit me.<\/p>\n The first thing v4 does is rip out the three lines every Tailwind project starts with. In v3 my In v4, that whole block collapses into a single import:<\/p>\n The upgrade CLI handled this fine on both projects. What it didn’t handle was the fact that I had a custom CSS layer sitting between Fix: put overrides inside an explicit Ten minutes of debugging that could have been zero if I’d read one paragraph of the migration guide. The official v4 announcement<\/a> is worth reading before you touch anything.<\/p>\n The bigger conceptual change is that Before, in After, in The mapping is: Two things bit me here.<\/p>\n First, I had a JS-based color palette generator wired into my old config (chroma.js, do not ask). That doesn’t work anymore because there’s no JS execution step in v4’s config path. I ended up writing a small Node script that computes the color ramp once at build time and emits a Second, I lost my This is the one that made me swear at my laptop.<\/p>\n In v3, The upgrade CLI rewrites most of these in your source files. It does not rewrite them inside strings that get concatenated at runtime. My admin dashboard had a component like this:<\/p>\n The CLI can’t statically see Fix: I scanned my codebase for string interpolation in If you’re doing this at scale, On the smaller of my two projects I was using PostCSS with a hand-written config. v4 ships a proper Vite plugin, and Tailwind’s team basically wants you to switch to it if you’re on Vite. The migration looks like this.<\/p>\n Before:<\/p>\n After:<\/p>\n Build times on this project dropped from about 4.1s to 1.6s on a cold build, which lined up roughly with what I saw when I first tried the Oxide engine on its own<\/a>. Not a placebo, not sponsored, just faster.<\/p>\n The Next.js project was slightly more annoying because Next uses its own PostCSS pipeline. There the answer is the PostCSS plugin ( v4 drops IE 11 (obviously) but also raises the floor on modern browsers. It leans on For my marketing site, our analytics said 0.4% of traffic was on browsers below that line, so I moved on. For the admin app, I checked with the ops team and we’re on evergreen Chrome only, so also fine. If you have a compliance client on locked-down browsers, this is the one thing worth verifying before you upgrade. Tailwind is explicit that v3 stays supported for anyone who needs to hold the line.<\/p>\n Under the hood, v4 uses Lightning CSS<\/a> instead of PostCSS + autoprefixer, which is part of why the build is so much faster and also part of why old browser targets don’t work. Lightning CSS decides what to prefix based on your browserslist, and Tailwind’s baseline is stricter than autoprefixer’s default.<\/p>\n I want to close with the thing that surprised me most, because it’s the part the release notes undersell.<\/p>\n The dev server just feels faster. Not “here’s a benchmark faster.” Subjectively faster in the loop. HMR on a Tailwind class change was noticeable in v3, and it’s basically instant in v4. Combined with the CSS-based config, my whole loop is: edit a class, save, see it. No config file to remember. No restart when I change theme tokens. The build step stopped feeling like a thing.<\/p>\n The other quiet win is that container queries are first-class now. I’d been half-heartedly using them via a plugin in v3 and it always felt bolted on. v4 makes them the default way to think about component-level responsiveness, which is a shift I wrote about in more detail in the container queries post<\/a>. If you’re building any kind of dashboard or component library, that one change alone justifies the upgrade for me.<\/p>\nThe @tailwind directives are gone, and yes it matters<\/h2>\n
globals.css<\/code> had:<\/p>\n@tailwind base;\n@tailwind components;\n@tailwind utilities;\n<\/code><\/pre>\n@import "tailwindcss";\n<\/code><\/pre>\n@tailwind base<\/code> and @tailwind components<\/code> where I patched a few resets. When it collapsed everything into one import, my layer ordering flipped and my custom reset ran after Tailwind’s, which meant my body font-family got clobbered on the marketing site.<\/p>\n@layer<\/code> block so ordering is deterministic.<\/p>\n@import "tailwindcss";\n\n@layer base {\n body { font-family: "Inter Variable", system-ui, sans-serif; }\n}\n<\/code><\/pre>\nThe config file didn’t move, it dissolved<\/h2>\n
tailwind.config.js<\/code> is optional in v4. Theme tokens live in CSS now, inside a @theme<\/code> block. I wrote a whole separate post about the Tailwind CSS v4 config file I deleted<\/a> so I won’t relitigate the philosophy here, but the migration shape looks like this.<\/p>\ntailwind.config.js<\/code>:<\/p>\nmodule.exports = {\n theme: {\n extend: {\n colors: {\n brand: {\n 50: "#f4f8ff",\n 500: "#3358ff",\n 900: "#0a1a5a",\n },\n },\n fontFamily: {\n display: ["Cabinet Grotesk", "sans-serif"],\n },\n },\n },\n};\n<\/code><\/pre>\nglobals.css<\/code>:<\/p>\n@import "tailwindcss";\n\n@theme {\n --color-brand-50: #f4f8ff;\n --color-brand-500: #3358ff;\n --color-brand-900: #0a1a5a;\n --font-display: "Cabinet Grotesk", sans-serif;\n}\n<\/code><\/pre>\ntheme.extend.colors.brand.500<\/code> becomes the CSS variable --color-brand-500<\/code>, and Tailwind generates bg-brand-500<\/code>, text-brand-500<\/code>, and the rest from it. Same for fontFamily.display<\/code> \u2192 --font-display<\/code> \u2192 font-display<\/code>.<\/p>\ntheme.css<\/code> file that I @import<\/code> before the main Tailwind import.<\/p>\nplugins: [require(\"@tailwindcss\/typography\")]<\/code> line and forgot to add it back. Prose styles just weren’t there. The v4 way is to add @plugin<\/code> inside the CSS: @plugin \"@tailwindcss\/typography\";<\/code>. Another five minutes of “why is my blog body ugly again.”<\/p>\nThe utility renames that quietly changed my design<\/h2>\n
shadow-sm<\/code> was a subtle shadow and shadow<\/code> was medium. In v4 the scale shifted: what was shadow-sm<\/code> is now shadow-xs<\/code>, and what was plain shadow<\/code> is now shadow-sm<\/code>. Same story for parts of the blur<\/code>, rounded<\/code>, and outline<\/code> scales.<\/p>\nconst size = compact ? "sm" : "md";\nreturn <div className={`shadow-${size} rounded-${size}`}>...<\/div>;\n<\/code><\/pre>\nshadow-${size}<\/code>, so it left it alone. Result: my dashboard’s card shadows got heavier overnight because shadow-sm<\/code> in v4 renders like v3’s shadow<\/code>. Nothing crashed. Nothing threw a warning. The design just drifted.<\/p>\nclassName<\/code> values and switched to a static lookup table. In hindsight I should never have been doing runtime className concatenation for design tokens, but v3 was permissive and I got lazy.<\/p>\ngrep -rn 'className={<\/code>[^]*${' src\/<\/code> is a decent first pass to find the interpolations you actually need to fix. It’ll miss some (template literals split across lines) but it catches the obvious ones.<\/p>\nPostCSS is out, Vite is in, npm scripts change<\/h2>\n
\/\/ postcss.config.js\nmodule.exports = {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n};\n<\/code><\/pre>\n\/\/ vite.config.ts\nimport tailwindcss from "@tailwindcss\/vite";\n\nexport default {\n plugins: [tailwindcss()],\n};\n<\/code><\/pre>\n@tailwindcss\/postcss<\/code>), which is supported and works fine. If you’re on Next 15+ you don’t need to touch anything except swap the plugin name.<\/p>\nBrowser support is now a real conversation<\/h2>\n
@property<\/code>, cascade layers, color-mix()<\/code>, and container queries. All of those need Safari 16.4+, Firefox 128+, and Chromium 111+.<\/p>\nThe dev experience is quietly a lot nicer<\/h2>\n