I put off upgrading a client project to Tailwind v4 for four months. I’d read the release notes, watched Adam’s video twice, and still convinced myself the CSS-first config was going to break something obscure at the worst possible moment. Then a PR reviewer asked why I was still shipping v3.4 and I ran out of good excuses.<\/p>\n
So I did it on a Sunday. A Next.js 15 app, roughly 40 components, custom design tokens, dark mode, and a plugin I’d stopped remembering how to configure. Here’s what actually happened, what the v4 announcement<\/a> undersells, and the one snag that ate ninety minutes I wasn’t expecting to spend.<\/p>\n If you’ve only skimmed the release, three things matter more than the rest.<\/p>\n The config file is gone. Well, not gone gone. You can still write a The build engine got rewritten. The new engine (they call it Oxide) is a Rust rewrite of what used to be a PostCSS plugin chain. In my project, a full production build went from 4.2s to 0.7s. Dev incrementals dropped below 100ms, which is the first time in years that Tailwind has felt genuinely instant instead of “almost instant”.<\/p>\n The three That’s the whole change to your entry CSS file. Nobody warned me it was going to feel that clean.<\/p>\n The best part of v4, for me, is that design tokens now live in the same file as the CSS that uses them. In v3, editing a color meant hopping between Here’s a shortened before-and-after from a real project.<\/p>\n v3, config-first:<\/p>\n v4, CSS-first:<\/p>\n Two things I didn’t appreciate until I lived with it for a week.<\/p>\n First, every one of those variables is a real CSS custom property. So I can use Second, dark mode gets simpler. Instead of a JS predicate in the config, I redefine tokens under a Every framework release claims a speed bump nobody notices. This one I noticed. My CI pipeline shaved almost four seconds off the CSS build step alone, which added up over a hundred builds a day.<\/p>\n More important: the dev experience feels different. When I edit a class name in a component and save, the browser paints the new style before I can move my hand to the mouse. That was already true of Vite. It wasn’t true of Tailwind’s own rebuild step. Now it is.<\/p>\n If you’re on a large monorepo, the speed matters more than you’d expect. A teammate on a much bigger codebase told me their editor’s Tailwind IntelliSense stopped stalling on the third autocomplete. That was worth the upgrade all by itself.<\/p>\n For a deeper look at why the Rust rewrite behaves this way, the official upgrade guide<\/a> has the honest performance numbers. The 10x claim is real for cold builds. For incremental dev builds, it’s closer to 5x. Both feel great in practice.<\/p>\n Not everything went smoothly. Here’s the ninety-minute snag.<\/p>\n I had a handful of custom utilities registered via a v3 plugin. Something like a The fix, once I stopped fighting it, was to move that utility into plain CSS using Cleaner than the plugin, honestly. But I wouldn’t have found One other papercut worth mentioning. If you were using arbitrary breakpoints like And if you rely on If you’re on v3 and shipping actively, upgrade. Not next quarter, this week. The dev-loop speed alone pays for the migration inside a sprint, and the config-in-CSS story makes new components measurably faster to write. It’s the first Tailwind release where I felt like the framework got out of my way instead of adding another layer.<\/p>\n If you’re on v3 and coasting on a legacy project, you can wait. v3 isn’t going anywhere fast, and the migration isn’t zero-cost for large plugin footprints. But even then I’d budget a day this quarter to at least run the codemod on a branch and see how much of the diff is scary. In my case, ninety percent of it was mechanical.<\/p>\n If you write a lot of custom utilities or design-system code, learn the What v4 actually changed<\/h2>\n
tailwind.config.js<\/code> if you want. But the recommended path is a CSS file with a @theme<\/code> block, and the framework reads that directly. Everything from colors to breakpoints to the typography scale now lives in CSS. That sounds like a small shuffle. It isn’t.<\/p>\n@tailwind<\/code> directives collapsed into one line. This one is small but everyone stubs a toe on it during migration, so:<\/p>\n\/* v3 *\/\n@tailwind base;\n@tailwind components;\n@tailwind utilities;\n\n\/* v4 *\/\n@import "tailwindcss";\n<\/code><\/pre>\nThe @theme block that replaced tailwind.config.js<\/h2>\n
tailwind.config.js<\/code>, the CSS entry file, and the JSX that consumes the class. Now it’s one file, and the tokens are actual CSS custom properties.<\/p>\n\/\/ tailwind.config.js\nmodule.exports = {\n content: [".\/src\/**\/*.{ts,tsx}"],\n theme: {\n extend: {\n colors: {\n brand: {\n 50: "#f5f7ff",\n 500: "#4f46e5",\n 900: "#1e1b4b",\n },\n },\n fontFamily: {\n display: ["Inter Display", "sans-serif"],\n },\n },\n },\n};\n<\/code><\/pre>\n@import "tailwindcss";\n\n@theme {\n --color-brand-50: #f5f7ff;\n --color-brand-500: #4f46e5;\n --color-brand-900: #1e1b4b;\n\n --font-display: "Inter Display", sans-serif;\n}\n<\/code><\/pre>\nvar(--color-brand-500)<\/code> inside a @media<\/code> query, or inside a calc()<\/code>, or inside a component library that doesn’t know Tailwind exists. In v3 those tokens only existed at build time. Now they’re regular CSS, which means the rest of my stylesheet gets to reuse them for free.<\/p>\n@media<\/code> block or a class selector, and the whole utility set updates. No dark:<\/code> prefix required for tokens that are already themed at the variable level.<\/p>\nThe Oxide engine and what “10x faster” actually means<\/h2>\n
Where the migration bit me<\/h2>\n
.text-balance-safe<\/code> helper that fell back to text-wrap: balance<\/code> with a browser check. In v4 the plugin API changed shape, and the automatic migration codemod turned my plugin into a broken CSS block that half-worked and half-didn’t.<\/p>\n@utility<\/code>. Which is the v4 way of extending Tailwind: skip the plugin entirely, write real CSS, and let the framework compose it into the utility layer.<\/p>\n@utility text-balance-safe {\n text-wrap: balance;\n @supports not (text-wrap: balance) {\n text-wrap: pretty;\n }\n}\n<\/code><\/pre>\n@utility<\/code> without an hour of digging through the migration docs and the changelog. That’s the piece the marketing didn’t sell hard enough: v4 wants you to write CSS, not JavaScript.<\/p>\nmin-[820px]:flex<\/code>, those still work, but the way custom breakpoints get declared in the @theme<\/code> block feels different enough that I broke a couple of them on the first pass. Twenty minutes with the console open sorted it out.<\/p>\n@apply<\/code> inside component CSS, be aware that v4 tightened up when it’s willing to compose utilities. A few of my CSS Modules stopped inlining tokens because I was calling @apply<\/code> from a scope Tailwind didn’t consider a utility layer. The fix was a one-line @reference<\/code> declaration at the top of the file, but the error message pointing me at it wasn’t obvious.<\/p>\nWhat I’d tell you to do this week<\/h2>\n
@utility<\/code> and @variant<\/code> at-rules before you migrate. The plugin story is deemphasized in v4 on purpose. The CSS-first way is more powerful once you accept it. I wrote about a related shift toward CSS-native tooling in my CSS Subgrid deep-dive<\/a> if you want more context on where the platform is heading.<\/p>\n