How to Upgrade Tailwind CSS v3 to v4 in a React + Vite Project (Step-by-Step)

Upgrading Tailwind CSS from v3 to v4 is one of the biggest frontend improvements for modern projects. Tailwind v4 introduces a faster Rust-based engine, removes unnecessary configuration files, and adopts a CSS-first configuration approach, making it perfect for React + Vite projects.

This article walks you through the complete migration process, explains why each step is required, and provides clean code examples and directory structure.

---

What’s New in Tailwind CSS v4

Before upgrading, let’s understand the major changes:

• 🚀 New Rust-based compiler (much faster)
• ❌ No tailwind.config.js by default
• ❌ No postcss.config.js
• ✅ CSS-first configuration using @theme and @layer
• ⚡ Faster builds with Vite

---

Existing Tailwind v3 Project Structure

A typical React + Vite + Tailwind v3 setup looks like this:

my-app/
├── index.html
├── postcss.config.js
├── tailwind.config.js
├── package.json
├── vite.config.js
└── src/
    ├── App.jsx
    ├── main.jsx
    └── index.css

---

Step 1: Remove Tailwind v3 Dependencies

Uninstall Tailwind v3 and related tooling:

npm uninstall tailwindcss postcss autoprefixer

Tailwind v4 no longer relies on PostCSS or Autoprefixer.

---

Step 2: Install Tailwind CSS v4

Install the latest Tailwind CSS version:

npm install tailwindcss@latest

No initialization command is needed.

---

Step 3: Remove Old Configuration Files

Delete the following files:

tailwind.config.js
postcss.config.js

Why?

Tailwind v4 automatically detects your files and uses CSS-based configuration instead of JavaScript.

---

Step 4: Update Your Main CSS File

Open src/index.css.

Tailwind v3 Syntax (Old)

@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind v4 Syntax (New)

@import "tailwindcss";

This single line replaces all previous Tailwind directives.

---

Step 5: Configure Theme and Utilities (CSS-First)

Tailwind v4 moves configuration into CSS.

@import "tailwindcss";

@theme {
  --color-brand: #2563eb;
  --font-display: "Inter", sans-serif;
}

@layer utilities {
  .center {
    @apply flex items-center justify-center;
  }
}

Benefits

• No JavaScript config file
• Faster builds
• Easier maintenance

---

Step 6: Ensure CSS Is Imported in React

Update src/main.jsx:

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./index.css";

ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

---

Step 7: Test Tailwind v4

Update App.jsx:

export default function App() {
  return (
    <div className="min-h-screen bg-slate-900 text-white flex items-center justify-center">
      <h1 className="text-4xl font-bold text-brand">
        Tailwind CSS v4 with React + Vite 🚀
      </h1>
    </div>
  );
}

Run the project:

npm run dev

If styles apply correctly, the upgrade is successful.

---

Final Project Structure (Tailwind v4)

my-app/
├── index.html
├── package.json
├── vite.config.js
└── src/
    ├── App.jsx
    ├── main.jsx
    └── index.css

Cleaner, faster, and easier to maintain.

---

Common Migration Issues

Tailwind styles not working

• Restart the dev server
• Ensure @import "tailwindcss"; exists
• Ensure CSS is imported in main.jsx

Custom theme missing

• Move theme values to @theme in CSS
• Do not use tailwind.config.js

---

Performance Improvements After Upgrade

• Faster cold starts
• Instant rebuilds
• Smaller dependency tree
• Ideal for Vite-powered projects

---

Conclusion

Tailwind CSS v4 simplifies frontend development by removing unnecessary configuration and embracing modern tooling. For React + Vite projects, upgrading from v3 to v4 results in cleaner code, faster builds, and a better developer experience.

If you’re building modern web apps in 2026, Tailwind v4 is the right choice.

---