Confession: I sat on the Tailwind v4 upgrade for almost three months after it shipped. Not because I read a scary thread on X. Because I’d already burned a Saturday on the v2-to-v3 jump and wasn’t excited to do it again.<\/p>\n
When I finally did it on a real production app this March, the actual code changes took maybe ninety minutes. The thing that ate my afternoon was a single CSS module file using I’ll skip the marketing pitch (it’s faster, the colors are nicer, etc.) and walk through the things I actually had to fix. The whole upgrade in numbers: a Next.js 15 app with about 240 components, three custom plugins, two themes (light and a “high-contrast” mode for one client), and a pile of Before v4, the canonical setup was Here’s how my brand color setup looked in v3:<\/p>\n And the v4 equivalent, in Two things to flag. First, you can drop the For projects with a lot of custom JS in their config (functions, deep merges, generated palettes), v4 still supports This is the one that ate my afternoon. v4 split the way utilities are exposed to scoped contexts: Vue’s After upgrading, this compiled, didn’t throw, and produced nothing. The class existed in the DOM with zero styles attached. The fix is documented in the Tailwind v4 upgrade guide<\/a>, and once you know the rule it’s obvious. I had to find it by reading a GitHub issue.<\/p>\n The plugin packages got renamed. The PostCSS plugin moved out of the main package into My v3 v4:<\/p>\n Autoprefixer goes away because v4 ships its own prefixing. If you’re on Vite, drop PostCSS entirely:<\/p>\n That cut my dev startup from about 1.4 seconds to under 400ms on the same machine. Some of that is the new Oxide engine, some is just skipping a layer of tooling. I won’t claim 10x like the marketing says, but on a hot edit my browser refreshes feel instant in a way they didn’t before.<\/p>\n Third-party plugins are the place to actually slow down. This is the boring section that’s actually the dangerous one. A few default utilities changed values, and the diffs are subtle enough that a designer eyeballing the staging site is going to be the one who flags them, usually right before launch.<\/p>\n The one that got me: I had to discover the change by squinting at a Figma file next to my staging site and going “wait, that looks off.” Ring color also changed (it was A few other defaults that moved.<\/p>\n The default container utility is gone. If you used Default border color is now I didn’t notice any of these in my unit tests. Nothing failed. The visual regression tests caught two of them. The third (the rings) I caught with my eyes. If you don’t have visual regression for your design-heavy pages, it’s worth standing up Playwright snapshots for the migration even if you tear them down after.<\/p>\n Three things, in order of how badly I wish I’d known them.<\/p>\n First, run the upgrade tool on a branch and read the diff before you do anything else. The official Second, search your codebase for Third, if you’re using TypeScript and have a If you’re upgrading a real production app, set aside an afternoon, not a Saturday. Branch the project, run the upgrade tool, fix The migration’s friendly. The defaults aren’t. Read the diff before you trust the diff.<\/p>\n","protected":false},"excerpt":{"rendered":" I sat on the Tailwind v4 upgrade for three months. Here’s what actually broke when I migrated a production Next.js app, and what I’d do differently.<\/p>\n","protected":false},"author":2,"featured_media":216,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"I sat on the Tailwind v4 upgrade for three months. Here's what actually broke when I migrated a production Next.js app, and what I'd do differently.","rank_math_focus_keyword":"tailwind css v4 migration guide","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[138,35],"tags":[37,38,40,139,36,134,39],"class_list":["post-217","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-frontend","category-web-development","tag-css","tag-frontend","tag-migration","tag-tailwind","tag-tailwind-css","tag-tailwind-v4","tag-web-development"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/217","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=217"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/217\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/216"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=217"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=217"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=217"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}@apply<\/code> that quietly stopped working with no error message, just the wrong styles. If you’re looking for a Tailwind CSS v4 migration guide that’s honest about the rough edges, this is mine.<\/p>\n@apply<\/code> rules I’d been embarrassed to look at for a year.<\/p>\nThe config file move was the loudest change, and the easiest<\/h2>\n
tailwind.config.js<\/code> at the project root. v4 wants the config inside your CSS, in an @theme<\/code> block. The official v4 release post on tailwindcss.com<\/a> walks through the reasoning. The short version: your design tokens already want to be CSS variables, so why are they JavaScript?<\/p>\n\/\/ tailwind.config.js\nmodule.exports = {\n content: ['.\/src\/**\/*.{js,ts,jsx,tsx}'],\n theme: {\n extend: {\n colors: {\n brand: {\n 50: '#f0f7ff',\n 500: '#2b6cff',\n 900: '#0a2454',\n },\n },\n fontFamily: {\n sans: ['Inter', 'system-ui', 'sans-serif'],\n },\n },\n },\n}\n<\/code><\/pre>\napp.css<\/code>:<\/p>\n@import "tailwindcss";\n\n@theme {\n --color-brand-50: #f0f7ff;\n --color-brand-500: #2b6cff;\n --color-brand-900: #0a2454;\n\n --font-sans: "Inter", system-ui, sans-serif;\n}\n<\/code><\/pre>\ncontent<\/code> glob entirely if you’re using the Vite plugin or the new automatic source detection. Tailwind walks your project and figures it out. Second, every theme variable becomes a real CSS custom property at runtime. So bg-brand-500<\/code> and var(--color-brand-500)<\/code> reference the same value. That sounds boring on paper, but it changes how I write components: a Headless UI dialog overlay can pull var(--color-brand-500)<\/code> directly without knowing Tailwind exists. I wrote about living with this setup six months on in my Tailwind v4 config notes<\/a>, and I haven’t missed the JS file.<\/p>\n@config \".\/tailwind.config.js\"<\/code> as an escape hatch. I used that during the migration window so I could move things over piece by piece instead of doing a big-bang rewrite.<\/p>\n@apply in scoped CSS files needs @reference now<\/h2>\n
<style scoped><\/code>, CSS modules, Svelte’s <style><\/code>, anything that doesn’t share Tailwind’s main scope. My main app.css<\/code> was fine. But Button.module.css<\/code> had something like:<\/p>\n\/* v3, worked fine *\/\n.primary {\n @apply bg-brand-500 text-white px-4 py-2 rounded-lg;\n}\n<\/code><\/pre>\n\/* v4, works *\/\n@reference "..\/app.css";\n\n.primary {\n @apply bg-brand-500 text-white px-4 py-2 rounded-lg;\n}\n<\/code><\/pre>\n@reference<\/code> tells the scoped file where to find your theme without re-emitting the whole Tailwind base. Skip it and @apply<\/code> runs in a vacuum. You get a class with no styles. No warning, just sad buttons. If you have any module CSS or scoped styles in your app, grep for @apply<\/code> before you upgrade and add the reference at the top of every file that needs it.<\/p>\nPlugins, PostCSS, and Vite: the install dance<\/h2>\n
@tailwindcss\/postcss<\/code>, and there’s a first-party Vite plugin now (@tailwindcss\/vite<\/code>) that’s faster than going through PostCSS at all.<\/p>\npostcss.config.js<\/code>:<\/p>\nmodule.exports = {\n plugins: {\n tailwindcss: {},\n autoprefixer: {},\n },\n}\n<\/code><\/pre>\n\/\/ postcss.config.js\nexport default {\n plugins: {\n "@tailwindcss\/postcss": {},\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\/forms<\/code>, @tailwindcss\/typography<\/code>, and @tailwindcss\/aspect-ratio<\/code> all had v4-compatible releases by the time I migrated. A community plugin I was using for a custom prose theme didn’t, and I had to inline its rules into @theme<\/code> and a small @layer components<\/code> block. Check every plugin’s release notes before you start. If you’ve got a plugin author who’s gone quiet, budget time to copy out their CSS.<\/p>\nDefault values changed in ways your designer will notice<\/h2>\n
ring<\/code> used to be 3px. In v4 it’s 1px by default. So every focus ring on every input across the app got skinnier overnight. The fix is one line:<\/p>\n@theme {\n --default-ring-width: 3px;\n}\n<\/code><\/pre>\ncurrentColor<\/code> derived in v3, now it’s a theme token), so check anywhere you’d assumed the old behavior.<\/p>\nspace-x-*<\/code> and space-y-*<\/code> use :not(:last-child)<\/code> instead of the old > * + *<\/code> selector. If you had any flexed layout where last-child<\/code> wasn’t the visual last child (think flex-row-reverse<\/code>), the spacing flips.<\/p>\ncontainer mx-auto<\/code>, you now define one in @theme<\/code> or write your own.<\/p>\ncurrentColor<\/code> instead of gray-200<\/code>. Every border<\/code> without an explicit color reads from the surrounding text color now. I had a few divider lines that had been quietly relying on the old gray default.<\/p>\nWhat I’d do differently next time<\/h2>\n
npx @tailwindcss\/upgrade<\/code> command got my project 80% of the way there. I ran it, eyeballed the diff, undid the parts I wasn’t ready for, and committed the rest in chunks. That alone would have saved me half my time.<\/p>\n@apply<\/code> and triage every file. Files inside scoped contexts need @reference<\/code>. Files in your main entry don’t. I should have done this in five minutes at the start. Instead I debugged a styleless component for forty.<\/p>\ntailwind.config.ts<\/code> that’s importing types from tailwindcss<\/code>, those types still work, but the import path may have shifted. I had a typed plugin where import type { Config } from 'tailwindcss'<\/code> started warning. Painless fix, but worth knowing before you panic about your CI failing on type-check.<\/p>\n@apply<\/code>, re-test your forms (they’re the most likely place for ring and border defaults to bite), and ship it behind a flag if you can. I’ve been shipping under v4 in a couple of client projects on my work page<\/a>, and the dev experience win is bigger than I expected. The build speed is the obvious thing. The quieter win is that my design tokens finally live in one file, in CSS, where the rest of my app can see them.<\/p>\n