The Oxide engine, CSS-first configuration with @theme, renamed utilities and the automatic upgrade tool — everything you need to move a real project from Tailwind v3 to v4.

Francis K Njenga
Senior Developer
Tailwind CSS v4 is the biggest rewrite in the framework's history: a new Rust-powered Oxide engine (full builds up to ~10× faster, incremental builds in microseconds), a CSS-first configuration model that replaces tailwind.config.js for most projects, and a simplified install with no PostCSS plugin chain to babysit. It has been stable since January 2025 and is now the default for new projects — but migrating an existing v3 codebase has real breaking changes. Here is the map.
| Area | v3 | v4 |
|---|---|---|
| Configuration | tailwind.config.js | @theme in your CSS (JS config still possible via @config) |
| Entry CSS | @tailwind base/components/utilities | @import "tailwindcss" |
| PostCSS | tailwindcss plugin + autoprefixer | @tailwindcss/postcss (or the Vite plugin) |
| Content detection | content: [...] globs | Automatic (respects .gitignore); @source for extras |
| Browser floor | Older browsers via transpilation | Safari 16.4+, Chrome 111+, Firefox 128+ (uses @property, color-mix()) |
Check the browser floor first. If your analytics show meaningful traffic on older browsers, v4 is not a drop-in upgrade — that is the one change the migration tool cannot fix for you.
The official codemod handles the mechanical 80%: dependencies, entry CSS, config conversion and most utility renames. Run it on a clean branch and review the diff like any other PR.
# from the project root, on a fresh branch
npx @tailwindcss/upgrade
# what it does:
# - tailwindcss -> v4, adds @tailwindcss/postcss (or @tailwindcss/vite)
# - removes autoprefixer + postcss-import (now built in)
# - rewrites @tailwind directives to @import "tailwindcss"
# - converts tailwind.config.js theme extensions into @theme
# - renames utilities across your templatesAlways commit before running — you want a reviewable diff, not a surprise.
Design tokens now live in CSS as regular custom properties inside @theme. Every token automatically becomes utilities and a CSS variable you can use anywhere — no more theme() lookups or arbitrary values for your own palette:
/* v3: tailwind.config.js
theme: { extend: { colors: { ink: { 950: "#05080f" } },
fontFamily: { display: ["Space Grotesk"] } } } */
/* v4: */
@import "tailwindcss";
@theme {
--color-ink-950: #05080f;
--color-ink-900: #0a0f1a;
--color-mist-100: #e8eef7;
--color-mist-300: #b6c2d4;
--color-accent-400: #22d3ee;
--font-display: "Space Grotesk", sans-serif;
--ease-expo: cubic-bezier(0.16, 1, 0.3, 1);
}
/* tokens are also plain variables: */
.card { border-color: var(--color-ink-900); }bg-ink-950, text-mist-300, font-display — generated straight from these tokens.
v4 cleaned up the scale naming, which means some classes silently change meaning if you hand-migrate. The important ones:
| v3 | v4 | Note |
|---|---|---|
| shadow-sm | shadow-xs | The whole shadow/rounded/blur scales shifted one step — bare shadow now equals old shadow-sm, etc. |
| shadow | shadow-sm | |
| rounded-sm | rounded-xs | |
| rounded | rounded-sm | |
| outline-none | outline-hidden | outline-none now truly removes the outline |
| bg-opacity-50 | bg-black/50 | Opacity utilities removed — use the slash modifier |
| flex-shrink-0 / flex-grow | shrink-0 / grow | Old names still work but are deprecated |
| bg-gradient-to-r | bg-linear-to-r | Gradient utilities renamed (old names kept as aliases) |
currentColor, not gray-200. Anywhere you wrote bare border expecting gray, specify the color.space-x-*) changed selector strategy for performance — verify layouts with reversed/hidden children.@layer components/@layer base to restore v3-like precedence.flex! instead of !flex.bg-(--brand) shorthand for bg-[var(--brand)].For Next.js, swap the PostCSS plugin; for Vite projects, the dedicated plugin is faster and simpler:
// postcss.config.mjs (Next.js, CRA, etc.)
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};
// vite.config.ts alternative:
// import tailwindcss from "@tailwindcss/vite";
// export default defineConfig({ plugins: [react(), tailwindcss()] });Vite alternative: add tailwindcss() from @tailwindcss/vite to plugins and delete postcss.config.
npx @tailwindcss/upgradeborder and ring usages for the new defaultsShould you migrate? For active projects: yes — the engine speed alone pays for the afternoon, and v3 is in maintenance mode. For stable legacy apps with old-browser traffic: stay put, there is no security pressure to move.
Migrations like this are routine work for our team — if you want it done and verified without burning your sprint, hand it to us.

Senior Developer
Francis Njenga is an experienced Lead Developer specializing in React, Next.js, and modern JavaScript frameworks, with a strong background in web development.