Tailwind v4 is the largest version jump since the project's inception — a ground-up Rust rewrite (Oxide), CSS-first configuration via @theme, and a long list of small breaking changes that add up. By mid-2026 the ecosystem has caught up, and migration is genuinely the right move for most projects. This is the practical guide.
What changed in 2026
- Oxide engine ships in stable v4: Rust core + Lightning CSS for parsing/optimization. Build times drop 5-10× on real projects.
- CSS-first config via
@theme { } blocks replaces most of tailwind.config.js. JavaScript config still works as a shim for plugins.
- Plugin ecosystem caught up. Major libs (shadcn/ui, daisyUI, headlessui themes) released v4-compatible versions by Q1 2026.
What's actually breaking
The deprecations from v3 are now removed. The renames you'll hit:
- Removed: opacity utilities like
opacity-xx are still there, but the bg-opacity-50 syntax is gone. Use bg-black/50 (which already worked in v3).
- Renamed:
shadow-sm is now shadow-xs; shadow is shadow-sm. Every shadow utility shifted one notch.
- Removed:
blur-sm shifted similarly. Run the official codemod and it handles these.
- CSS variables: all theme values are now exposed as CSS custom properties (
--color-blue-500). Easy to consume; minor migration work if you used JavaScript config to expose colors yourself.
- Container queries: built-in (no plugin needed). Old plugin can stay during migration but should be removed.
- Browser support: Safari 16.4+, Chrome 111+. Drops IE entirely (was already dropped in v3) and old Safari.
The new @theme syntax
@import "tailwindcss";
@theme {
--color-brand-500: oklch(0.65 0.2 250);
--font-display: "Cabinet Grotesk", sans-serif;
--breakpoint-3xl: 120rem;
}
This replaces most of what was in tailwind.config.js > theme. Custom utilities (via @utility), variants (via @variant), and screens all live in CSS now.
Migration playbook
Step 1 (15 min): Verify dependencies. Most plugins should be on v4-compatible versions by now. Check tailwindcss-animate, @tailwindcss/forms, @tailwindcss/typography, and any custom plugins.
Step 2 (15 min): Run the official upgrade tool: npx @tailwindcss/upgrade. It handles the import statement change, the shadow renames, and migrates simple JS config to CSS @theme.
Step 3 (1-2 hr): Manually migrate complex JS config. Custom color palettes, plugin configurations, and theme extensions all need attention. The codemod handles primitives well but not nested objects.
Step 4 (30 min): Test build. The first build will be a revelation — what took 8 seconds now takes 1.5. CI deploy time drops noticeably.
Step 5 (ongoing): Audit shadows, opacity utilities, and custom variants. Most issues are visual, caught in review.
Comparison vs v3
| Aspect |
v3 |
v4 |
| Engine |
PostCSS plugin |
Oxide (Rust) + Lightning CSS |
| Build time (large app) |
5-10s |
0.5-2s |
| Config |
JS file |
CSS @theme + JS shim |
| Container queries |
Plugin |
Built-in |
| CSS variables |
Limited |
All theme values |
| Browser support |
Modern |
Safari 16.4+, Chrome 111+ |
| Migration effort |
— |
1 day for most teams |
Common gotchas
Custom plugins. Plugin authors had to migrate to the new API. Most popular plugins (animate, forms, typography) are done. Niche plugins may still be on v3 — verify before migrating.
Tailwind in monorepos. The new engine handles content scanning differently. If you have shared packages with Tailwind classes, you'll need explicit config to scan them.
JIT mode is gone. v4 is always-JIT. If you had mode: 'jit' in old config, it's a no-op now (and will warn).
Arbitrary values. Still work, but the bracket syntax is slightly more strict. Square-bracket values like mt-[var(--foo)] need quotation in some edge cases.
Should you migrate?
Yes: new projects, active codebases, anything where build speed matters.
Wait: apps with custom plugins not yet migrated, or apps in maintenance mode where the speed gain doesn't matter.
Skip: legacy projects in last-six-months-of-life. The migration time isn't repaid.
FAQ
Is the syntax really CSS now?
Mostly. JS config still works for compatibility. New projects can be config-less if defaults work.
Does it work with Vite, Next.js, Remix, Astro, etc.?
Yes — official adapters for all major frameworks landed in v4.0.
What about VS Code IntelliSense?
Tailwind CSS IntelliSense extension supports v4 fully — you may need to update.
How long does migration actually take?
Half a day for a typical Next.js or Vite app. A full day if you have complex custom plugins.
Where to go next
For related coverage see Biome vs ESLint + Prettier in 2026, Next.js 15 Server Actions guide in 2026, and TypeScript strict mode guide in 2026.