DEV Community

Cover image for 🔄 Real-World Migration Steps from Tailwind CSS v3 to v4
Mridu Dixit
Mridu Dixit

Posted on

🔄 Real-World Migration Steps from Tailwind CSS v3 to v4

#javascript #webdev #programming #tailwindcss

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
Enter fullscreen mode Exit fullscreen mode

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"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode 
// tailwind.config.js (v4)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "oklch(62.7% 0.194 149.214)" // ✅ OKLCH supported
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

👉 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>
Enter fullscreen mode Exit fullscreen mode
  • 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
Enter fullscreen mode Exit fullscreen mode

👉 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",
],
Enter fullscreen mode Exit fullscreen mode

👉 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);
}
Enter fullscreen mode Exit fullscreen mode 
<div class="bg-[var(--brand)]"></div>
Enter fullscreen mode Exit fullscreen mode
  • 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)