{"post":{"slug":"tailwind-v4-migration-guide-2026","title":"Tailwind CSS v4 migration guide in 2026: the engine rewrite, breaking changes, real upgrade plan","excerpt":"Tailwind v4 is a ground-up rewrite. This is the practical migration guide with the breaking changes that matter and the gotchas the docs gloss over.","category":"code","date":"February 10, 2026","author":"ByteLedger Team","content":"<span class=\"dropcap\">T</span>ailwind 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.\n\n## What changed in 2026\n\n- **Oxide engine** ships in stable v4: Rust core + Lightning CSS for parsing/optimization. Build times drop 5-10× on real projects.\n- **CSS-first config** via `@theme { }` blocks replaces most of `tailwind.config.js`. JavaScript config still works as a shim for plugins.\n- **Plugin ecosystem caught up.** Major libs (shadcn/ui, daisyUI, headlessui themes) released v4-compatible versions by Q1 2026.\n\n## What's actually breaking\n\nThe deprecations from v3 are now removed. The renames you'll hit:\n\n- **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).\n- **Renamed:** `shadow-sm` is now `shadow-xs`; `shadow` is `shadow-sm`. Every shadow utility shifted one notch.\n- **Removed:** `blur-sm` shifted similarly. Run the official codemod and it handles these.\n- **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.\n- **Container queries:** built-in (no plugin needed). Old plugin can stay during migration but should be removed.\n- **Browser support:** Safari 16.4+, Chrome 111+. Drops IE entirely (was already dropped in v3) and old Safari.\n\n## The new @theme syntax\n\n```css\n@import \"tailwindcss\";\n\n@theme {\n  --color-brand-500: oklch(0.65 0.2 250);\n  --font-display: \"Cabinet Grotesk\", sans-serif;\n  --breakpoint-3xl: 120rem;\n}\n```\n\nThis replaces most of what was in `tailwind.config.js > theme`. Custom utilities (via `@utility`), variants (via `@variant`), and screens all live in CSS now.\n\n## Migration playbook\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\n**Step 5 (ongoing)**: Audit shadows, opacity utilities, and custom variants. Most issues are visual, caught in review.\n\n## Comparison vs v3\n\n| Aspect | v3 | v4 |\n| --- | --- | --- |\n| Engine | PostCSS plugin | Oxide (Rust) + Lightning CSS |\n| Build time (large app) | 5-10s | 0.5-2s |\n| Config | JS file | CSS @theme + JS shim |\n| Container queries | Plugin | Built-in |\n| CSS variables | Limited | All theme values |\n| Browser support | Modern | Safari 16.4+, Chrome 111+ |\n| Migration effort | — | 1 day for most teams |\n\n## Common gotchas\n\n**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.\n\n**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.\n\n**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).\n\n**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.\n\n## Should you migrate?\n\n**Yes:** new projects, active codebases, anything where build speed matters.\n\n**Wait:** apps with custom plugins not yet migrated, or apps in maintenance mode where the speed gain doesn't matter.\n\n**Skip:** legacy projects in last-six-months-of-life. The migration time isn't repaid.\n\n## FAQ\n\n**Is the syntax really CSS now?**\nMostly. JS config still works for compatibility. New projects can be config-less if defaults work.\n\n**Does it work with Vite, Next.js, Remix, Astro, etc.?**\nYes — official adapters for all major frameworks landed in v4.0.\n\n**What about VS Code IntelliSense?**\nTailwind CSS IntelliSense extension supports v4 fully — you may need to update.\n\n**How long does migration actually take?**\nHalf a day for a typical Next.js or Vite app. A full day if you have complex custom plugins.\n\n## Where to go next\n\nFor related coverage see [Biome vs ESLint + Prettier in 2026](/blog/biome-vs-eslint-prettier-2026), [Next.js 15 Server Actions guide in 2026](/blog/nextjs-15-server-actions-guide-2026), and [TypeScript strict mode guide in 2026](/blog/typescript-strict-mode-guide-2026).","hue":172,"metaTitle":"Tailwind v4 Migration Guide 2026: Breaking Changes & Plan","metaDescription":"Practical 2026 Tailwind CSS v4 migration guide — Oxide engine, CSS-first config, breaking changes, and the upgrade plan that actually works.","keywords":["tailwind v4 migration","tailwind css 4","tailwind oxide engine","tailwind v3 to v4","tailwind css migration 2026","tailwind breaking changes","lightning css tailwind","tailwind config migration","tailwind theme css","tailwind upgrade guide"],"tldr":["**Tailwind v4 is 5-10× faster** than v3 thanks to the Oxide engine (Rust + Lightning CSS).","**Config moves from JavaScript to CSS** via @theme — most projects will keep tailwind.config.js as a shim.","**Breaking changes: removed deprecated utilities, renamed shadow scale, opacity syntax.**","**Skip:** migrating until you're on a release with stable plugin support — major plugins took 4-6 months to catch up."],"readTime":"4 min read","wordCount":774},"related":[{"slug":"ai-for-code-migration-2026","title":"AI for Code Migration in 2026: A Practical Guide","excerpt":"AI coding agents can now port languages, upgrade frameworks, and migrate large codebases in hours instead of weeks. Here is what actually works in 2026, and where a human still has to step in.","category":"ai","date":"July 8, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":305},{"slug":"how-to-learn-numpy-2026","title":"How to learn NumPy in 2026: arrays, broadcasting, and real-world speed","excerpt":"NumPy 2.x with Python 3.12+ is faster and stricter about copy semantics than ever. Master it before pandas or TensorFlow — every other library builds on top of it.","category":"code","date":"April 16, 2026","author":"ByteLedger Team","readTime":"5 min read","hue":305},{"slug":"how-to-learn-tailwind-css-2026","title":"How to learn Tailwind CSS in 2026: the practical roadmap","excerpt":"Tailwind CSS dominates utility-first styling in 2026, with v4 rewriting the config model. Here is the fastest honest path from zero to production-ready.","category":"code","date":"February 25, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":315}],"sameCategory":[{"slug":"bazel-build-explained-2026","title":"Bazel Explained: What Hermetic Builds Actually Cost","excerpt":"Bazel delivers reproducible, precisely cached builds and demands that you describe everything. Here is what you get, what it costs, and who should say no.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":145},{"slug":"graphql-federation-2026","title":"GraphQL Federation: One Graph, Many Teams","excerpt":"Federation composes independently-owned subgraphs into a single API. Here is what it solves, the operational cost it adds, and when a simpler gateway is enough.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":300},{"slug":"hermetic-builds-explained-2026","title":"Hermetic Builds Explained: Same Inputs, Same Output","excerpt":"A hermetic build depends only on declared inputs. Here is what that property gives you, the common leaks that break it, and how to move toward it incrementally.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":130},{"slug":"monorepo-tooling-compared-2026","title":"Monorepo Tooling Compared: What You Actually Need","excerpt":"Monorepo tools solve task orchestration and caching, not repository layout. Here is what each tier provides and how to tell when you have outgrown the simple option.","category":"code","date":"August 19, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":150}],"newer":{"slug":"schema-drift-detection-2026","title":"Schema Drift: When Environments Stop Matching","excerpt":"Production has an index staging does not. Someone added a column by hand during an incident. Migrations pass everywhere and behaviour differs, and nobody knows why.","category":"code","date":"February 10, 2026","author":"ByteLedger Team","readTime":"4 min read","hue":318},"older":{"slug":"tanstack-router-vs-react-router-2026","title":"TanStack Router vs React Router in 2026: which to ship","excerpt":"The React routing landscape settled in 2026. Here's the honest comparison of TanStack Router and React Router — and when each one is the right pick.","category":"code","date":"February 10, 2026","author":"ByteLedger Team","readTime":"3 min read","hue":165}}