Tailwind v4 in Production in 2026: Migration Strategy

This exact site runs Tailwind v3.4.18. It's sitting right there in package.json, next to two client codebases in the same spot, all three queued behind actual paying work. So when I talk about tailwind v4 migration, I'm not reciting a changelog I read once. I'm describing the plan I'm about to run on my own production stack, the same stack recommended across the SaaS MVP tech stack I put in front of every client: Next.js, TypeScript, and the utility-first CSS approach Tailwind takes. If you're staring at the same unmigrated tailwind.config.js I am, this is the version of the guide that assumes you have customers who'd notice if you broke something — customers like the five to ten daily orders running through Pizzeria Bestek's checkout flow, where a broken layout is a lost sale, not an abstract regression.

What Actually Breaks When You Run Tailwind's Upgrade Tool?

The upgrade tool handles about 90% of the mechanical work and leaves the dangerous 10% for you to find by hand. Tailwind's own upgrade guide is explicit about this: npx @tailwindcss/upgrade rewrites your dependencies, migrates the JS config into CSS, and renames the classes it recognizes across your templates. It needs Node 20+, and it wants a clean git branch, not your main branch with uncommitted work sitting on top of it.

What it doesn't reliably catch: custom plugins written against the v3 addUtilities()/theme() API, safelist entries generated dynamically at runtime, and anything built on a string template that assembles class names outside plain JSX. If your codebase concatenates Tailwind classes with template literals based on a prop value, the codemod's static analysis has nothing to grep. It'll skip those silently. You won't find out until a component renders unstyled in front of an actual customer. Every single time.

Why Does the PostCSS Plugin Rename Break More Than the Codemod Admits?

The PostCSS plugin package itself changed names, and that single rename can break a build the codemod never touches. In v3, your postcss.config.js lists tailwindcss directly as a plugin. In v4, that entry point is dead — you need @tailwindcss/postcss instead, and postcss-import plus autoprefixer get folded in automatically, so leaving them in your config isn't wrong, exactly, it's just dead weight now.

Here's where it gets ugly for anyone running a monorepo or a shared UI package: if one internal package still resolves the old tailwindcss v3 PostCSS entry while your app resolves v4, the build doesn't warn you politely. It just breaks, and the error message rarely mentions Tailwind by name. A developer writing under the handle wishot_cipher documented exactly this failure mode: installing @tailwindcss/typography on top of a v4 project pulled in a nested tailwindcss@3.4.1 through the plugin's own dependency tree. It worked on next dev. It failed the Vercel build outright, because Vercel's install step is stricter about the conflict than a local dev server bothers to be. This repo runs @tailwindcss/typography today. That's not a hypothetical for me, it's next Tuesday.

Is the @tailwindcss/typography Plugin Safe to Keep on v4?

Only if you upgrade it alongside Tailwind itself, never before or after in a separate step. Ship the typography plugin bump in the same commit as the core tailwindcss bump, then run your build locally with a clean node_modules, not an incrementally-updated one, before you trust the lockfile. Skip that and you're the next dependency-tree surprise, discovered by whichever CI system is stricter than your laptop.

Tailwind v3 vs v4, Side by Side

| | Tailwind v3 | Tailwind v4 | |---|---|---| | Config format | tailwind.config.js (JS object) | @theme block inside CSS | | PostCSS plugin name | tailwindcss | @tailwindcss/postcss | | Minimum browser | IE11-era fallback tolerated | Safari 16.4+, Chrome 111+, Firefox 128+ | | flex-shrink-0 / flex-grow-0 | Valid | Renamed to shrink-0 / grow-0 | | Opacity utilities | bg-opacity-50 | bg-black/50 | | Default border color | gray-200 | currentColor | | Full build (Catalyst benchmark) | 378ms | 100ms |

That browser-support row is the one people skim past and shouldn't. Tailwind v4 depends on native @property and color-mix(), which means Safari below 16.4 and any pre-111 Chromium fork just doesn't get your styles right, full stop, no polyfill path. If your analytics show meaningful traffic on older Safari, v4 isn't ready for you yet, and no amount of codemod cleverness changes that.

Config-as-CSS Is Closer to a Real Design System Now

The old tailwind.config.js was a settings file. The @theme block is closer to an actual design system: every color, spacing value, and breakpoint becomes a real CSS variable, readable at runtime instead of vanishing after build time. That's the upgrade worth wanting, once the migration itself stops being the obstacle.

What Actually Got Faster in v4, With Real Numbers?

Full builds got roughly 3.78x faster on Tailwind's own benchmark, and incremental rebuilds with no new CSS now finish in microseconds instead of milliseconds. Tailwind Labs published the exact figures — 378ms to 100ms full builds, 35ms to 192 microseconds for cache-hit incrementals — in the January 22, 2025 v4.0 announcement, and the practical effect shows up during active development, not in your CI logs. Watch mode feels instant. Adding a class and seeing the browser update no longer has a perceptible gap, which sounds like a small thing until you've spent an afternoon nudging padding values one pixel at a time.

Actually — that undersells the part that matters at 11pm before a client demo. The old build step was slow enough that I'd batch style changes to avoid the wait. The new one is fast enough that I don't think about it, which changes how much I'm willing to iterate live instead of guessing offline. It's also a risk unique to the web. BookBed's mobile apps compile Flutter widget styling ahead of time into isolated bundles, so one bad style change ships to one screen. A Tailwind utility class change on the web cascades to every page that references it, the instant you deploy.

A Two-PR Migration Plan That Stays Shippable

Splitting the migration into two pull requests, mechanical first and manual second, keeps the diff reviewable and gives you a rollback point if something goes sideways in production.

1. PR one — the codemod, unreviewed by eye. Branch off main, run npx @tailwindcss/upgrade, commit the raw output without hand-editing it. Let CI run. This PR proves the automated 90% doesn't break the build on its own.
2. PR two — the manual 10%. Grep the codebase for addUtilities, theme(, and any dynamically-built class string. Fix custom plugins against the new @utility API. Re-add explicit border and ring colors everywhere you relied on the old gray-200 and blue-500 defaults — those defaults are gone entirely, and the codemod won't guess which color you meant.
3. Visual regression pass, by eye, not by snapshot test. Snapshot tests compare unstyled DOM structure and will happily pass while your spacing is silently wrong. Open the five highest-traffic pages in a real browser and look at them.
4. Deploy behind a feature flag or to a staging subdomain first, never straight to main on a Friday. CSS regressions have a wider blast radius than almost any backend bug, because a broken utility class doesn't fail one endpoint, it fails every page that used it, at once.
5. Watch error tracking and support inboxes for 48 hours, since layout regressions in dark mode or on mobile widths tend to get reported later than the obvious desktop-light ones.
6. Only then remove the old tailwind.config.js, postcss-import, and autoprefixer entries. Keep them stubbed until you're confident, since ripping them out early just makes reverting harder if PR two needs a second pass.

You've probably already spotted the missing step: nobody schedules a maintenance window for CSS. That's the actual reason these migrations slip for two quarters instead of two weeks. It's not the codemod. It's that a styling-only change never feels urgent enough to book calendar time for, right up until a customer screenshots a broken checkout page and the fix becomes urgent by force.

Does the Timing Actually Matter, or Is This Just Fear of Change?

It matters for supply-chain readiness, not out of fear of change: migrating before your key dependencies officially support v4 means inheriting their bugs on top of your own. Ecosystem plugins have been catching up through 2026 — DaisyUI 5 shipped native v4 support in February rather than a compatibility shim, which is the kind of signal worth waiting for if your project leans on a component library you don't control.

The Part Nobody Puts in the Changelog

Every renamed utility in that comparison table above is a find-and-replace problem. The default-value changes are the ones that cost you a support ticket, because border silently rendering as currentColor instead of a visible gray line doesn't throw an error. It just looks wrong, quietly, on every card component in production, and the first person to notice is usually a customer, not you. Have you actually grepped your codebase for bare border and ring classes yet, or are you assuming the codemod caught every one?

Run the upgrade tool this week if you're going to run it at all. Then tell me on whichever channel you found this post whether the border-color default is the one that got you too, because I'd bet it is.