Tailwind CSS v4 Migration Checklist (2026)

Frontend teams on Next.js/React often still carry Tailwind v3 debt: tailwind.config.js, @tailwind directives, and PostCSS plugins that no longer match v4. This is a practical production migration checklist. Primary reference: the official Tailwind CSS upgrade guide.

Related posts on ShopperCove:

• Next.js 16 App Router Production Checklist (2026)
• Build an AI Chat UI with Next.js & shadcn (2026)
• Next.js 16.3 for AI Coding Agents (2026)
• TanStack Start XSS: Patch CVE-2026-102989 Now
• AI SEO for Answer Engines: ChatGPT, Perplexity & Google AI (2026)
• Grow Site Traffic in the AI Search Era (2026)
• Lily in CI: Fuzz-Based Backdoor Detection
• Clozure AI Business OS Review

Affiliate disclosure. This post includes one optional ClickBank affiliate link for Clozure (seller nickname CLOZURE). If you buy through that link, ShopperCove may earn a commission at no extra cost to you. Clozure is not a CSS framework, Tailwind plugin, or Next.js dependency—only an optional AI business OS (email/calendar/CRM) some indie founders use. ShopperCove has not trialed Clozure for this migration guide. ClickBank is the retailer of products on this site. CLICKBANK® is a registered trademark of Click Sales, Inc., a Delaware corporation located at 1444 S. Entertainment Ave., Suite 410, Boise, ID 83709, USA, and used by permission. ClickBank’s role as retailer does not constitute an endorsement, approval, or review of these products or any claim, statement, or opinion used in promotion of these products.

1. Pre-flight before you touch CSS

1. Browser support gate — Tailwind v4 targets Safari 16.4+, Chrome 111+, and Firefox 128+. If you still must support older browsers, stay on v3.4 until that requirement changes.
2. Node.js 20+ — the official upgrade tool requires Node 20 or higher.
3. Clean git branch — commit or stash first. Run npx @tailwindcss/upgrade on a dedicated branch so you can review the full diff.
4. Inventory plugins — third-party plugins, old corePlugins toggles, Sass/Less, and CSS modules / SFC <style> blocks that @apply tokens (usual hand-fix zones).

2. Run the upgrade CLI (then read the diff)

For most apps, start here:

npx @tailwindcss/upgrade

Expect it to update dependencies, rewrite CSS directives, convert much of tailwind.config.js into @theme, and rename utilities. Common pitfalls: dirty git tree; still using the old tailwindcss PostCSS plugin instead of @tailwindcss/postcss; scripts calling npx tailwindcss instead of @tailwindcss/cli; skipping visual QA because the build passed.

Vite users: prefer @tailwindcss/vite. Next.js/React on PostCSS: switch the plugin package and drop postcss-import / autoprefixer when v4 already handles imports and prefixes.

3. Move tokens into @theme (keep a JS config only if you must)

v4’s big mental shift: theme lives in CSS.

@import "tailwindcss";

@theme {
  --color-brand: #3b82f6;
  --breakpoint-3xl: 120rem;
  --font-display: "Inter", system-ui, sans-serif;
}

Map habitually: colors → --color-*, screens → --breakpoint-*, spacing → --spacing-*. Prefer var(--color-…) over theme(colors.…). JS configs need an explicit @config—v4 no longer auto-detects them. v3 corePlugins / safelist / separator options do not carry over the same way; safelist with @source inline() when needed. Custom utilities use @utility; variants use @custom-variant. Add @source only for non-standard content paths.

4. Breaking changes that bite UI QA

Watch these in staging (full list lives in the upgrade guide):

• Renames — e.g. shadow → shadow-sm, shadow-sm → shadow-xs; same pattern for blur/rounded; outline-none → outline-hidden when you meant the old invisible outline; bare ring → ring-3 if you depended on 3px rings.
• Defaults — border-* / divide-* default to currentColor (not gray-200); ring default color likewise. Explicit colors prevent “invisible borders” surprises.
• Selectors — space-* / divide-* selector changes can shift spacing; prefer flex/grid + gap when layouts look wrong.
• Prefixes & important — prefixes look like variants (tw:flex); ! goes at the end of the class (bg-red-500!).
• CSS variables in arbitrary values — bg-(--brand) not bg-[--brand].
• No Sass/Less/Stylus as a companion preprocessor for Tailwind v4 stylesheets—treat Tailwind as the preprocessor.
• CSS modules / SFC @apply — use @reference to pull theme from the main CSS file, or use CSS variables directly.

shadcn/ui stacks usually migrate cleanly once tokens and borders are explicit—see our Next.js + shadcn AI chat UI notes if you share those primitives.

5. Production verification (do not skip)

1. Cold production build (not only dev).
2. Visual pass: dark mode, focus rings, forms, dialogs, cards with borders.
3. Responsive breakpoints you customized (including any @theme --breakpoint-*).
4. Storybook / Chromatic / Percy if you have them—utility renames are screenshot gold.
5. Confirm lockfile resolves tailwindcss v4 and the right @tailwindcss/* packages.
6. Redeploy—local node_modules alone does not fix CDN or CI images.

After CSS is green, keep App Router hygiene (Next.js 16 checklist) and treat dependency bumps seriously (TanStack Start CVE checklist).

Optional tool for indie founders (not a CSS dependency)

Migrating Tailwind does not require a new SaaS. Solo founders who also want email/calendar/CRM sometimes evaluate an AI business OS separately from CSS.

One disclosed option (vendor claims only; ShopperCove has not hands-on tested it for this guide):

​Clozure AI Business OS via ClickBank hop​

Skip it if you already have ops tooling or only came for the @theme / upgrade CLI checklist. Verify export, cancel, and access controls before putting customer data in any SaaS.

Printable Tailwind v4 checklist

1. Confirm modern browser targets + Node 20+
2. Branch + clean tree → npx @tailwindcss/upgrade
3. Switch PostCSS/Vite/CLI packages; drop obsolete PostCSS helpers
4. Land tokens in @theme; @config only if JS config must remain
5. Fix renames: shadows, rings, outline-hidden, borders with explicit colors
6. Fix @utility / @custom-variant / @reference for custom & SFC CSS
7. Visual + production build QA; redeploy
8. Ops tools last — Clozure-style OS only if founder ops need it

Ship the CSS upgrade first. Everything else is optional.