Tailwind CSS v4 introduces major improvements like an always-on JIT engine, OKLCH colors, and better theming. But how do you migrate an existing Tailwind v3 project without breaking things? Letβs walk through practical, real-world steps.
β‘ Step 1: Upgrade Dependencies
Run the following to upgrade:
npm install tailwindcss@latest postcss@latest autoprefixer@latest
If using Next.js, Vite, Angular, or React, ensure your build toolchain is updated to the latest versions for compatibility.
π¨ Step 2: Update Tailwind Config
Tailwind v4 introduces changes in config defaults.
- Remove deprecated options like mode: 'jit' (now always-on).
- Check if youβre using extended color palettes that now support OKLCH.
// tailwind.config.js (v3)
module.exports = {
mode: "jit", // β remove this
theme: {
extend: {
colors: {
brand: "#4f46e5"
}
}
}
}
// tailwind.config.js (v4)
module.exports = {
theme: {
extend: {
colors: {
brand: "oklch(62.7% 0.194 149.214)" // β
OKLCH supported
}
}
}
}
π Pitfall: If you used custom theme.screens or spacing overrides, double-check defaults β some baseline values were refined in v4.
π οΈ Step 3: Update Arbitrary Values
Tailwind v4 makes arbitrary values more powerful but stricter.
<!-- v3 -->
<div class="bg-[#4f46e5] text-[13px]"></div>
<!-- v4 -->
<div class="bg-[oklch(62.7%_0.194_149.214)] text-[13px]"></div>
- OKLCH gives better accessibility by controlling brightness and contrast.
- Arbitrary spacing (p-[18px]) and sizing remain valid, but double-check after upgrade.
π Step 4: Plugin Updates
Official plugins (forms, typography, aspect-ratio) have been updated for v4:
npm install @tailwindcss/forms @tailwindcss/typography @tailwindcss/aspect-ratio
π Pitfall: If you rely on community plugins, ensure theyβre compatible with v4. Some plugins (especially older ones) may break due to new plugin APIs.
π¦ Step 5: Ensure Proper Content Paths
Tailwind removes unused classes in production. Misconfigured paths can lead to missing styles.
// Good v4 config
content: [
"./src/**/*.{html,js,ts,jsx,tsx}",
"./public/index.html",
],
π Run npm run build and inspect the final CSS size to confirm tree-shaking works.
π§© Step 6: Test Theming with CSS Variables
Tailwind v4 has first-class support for CSS variables.
:root {
--brand: oklch(62.7% 0.194 149.214);
}
<div class="bg-[var(--brand)]"></div>
- Great for dynamic theming (light/dark/system).
- Works smoothly with design systems.
π§ͺ Step 7: Comprehensive Testing
- Run visual regression tests (or just check key UI flows).
- Validate dark mode (colors behave differently under OKLCH).
- Check responsive breakpoints (grid & flex may shift slightly).
- Use Lighthouse to compare performance before vs. after migration.
π Bonus: Migration Strategy Tips
- Small project? Upgrade directly β itβll take an hour or two.
- Large enterprise app? Use a dual-branch migration strategy (keep v3 in production while testing v4 on staging).
- Design system users? Update tokens first (colors, spacing, screens) before refactoring components.
π― Final Thoughts
Migrating from Tailwind v3 to v4 is straightforward but not βdrop-inβ for every project.
β The payoff is huge:
- Faster builds (thanks to JIT always-on).
- Modern color accuracy with OKLCH.
- Cleaner config with CSS variable theming.
- Smaller, more maintainable CSS.
π If youβre starting a new project in 2025 β go with Tailwind v4.
π If upgrading β do it step by step, test thoroughly, and enjoy the future-ready workflow.
Top comments (0)