---
description:
globs:
alwaysApply: false
---
# Tailwind CSS v4 Migration Guide

## **Key Changes in Tailwind CSS v4**
- **No PostCSS dependency**: v4 has built-in CSS processing
- **Simplified import**: Use `@import "tailwindcss"` instead of separate directives
- **Vite plugin**: Use `@tailwindcss/vite` for Vite integration
- **No config file needed**: Configuration through CSS custom properties

## **Complete Migration Steps**

### **1. Remove All v3 Dependencies**
```bash
# Remove all Tailwind v3 and PostCSS packages
npm uninstall tailwindcss @tailwindcss/postcss @tailwindcss/node @tailwindcss/oxide
npm uninstall autoprefixer postcss postcss-import
```

### **2. Install Tailwind CSS v4**
```bash
# Install v4 packages
npm install @tailwindcss/cli@next @tailwindcss/vite@next
npm install tailwind-merge  # For utility merging
```

### **3. Update CSS Import**
```css
/* ❌ DON'T: v3 style imports */
@tailwind base;
@tailwind components; 
@tailwind utilities;

/* ✅ DO: v4 single import */
@import "tailwindcss";
```

### **4. Update Vite Configuration**
```typescript
// ❌ DON'T: v3 PostCSS setup
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "tailwindcss";
import autoprefixer from "autoprefixer";

export default defineConfig({
  plugins: [react()],
  css: {
    postcss: {
      plugins: [tailwindcss(), autoprefixer()],
    },
  },
});

// ✅ DO: v4 Vite plugin
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});
```

### **5. Remove Configuration Files**
```bash
# Delete these files (v4 doesn't need them)
rm postcss.config.js
rm tailwind.config.js
```

## **v4 Configuration (Optional)**

### **CSS-based Configuration**
```css
/* src/index.css */
@import "tailwindcss";

/* Custom theme configuration */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --font-family-custom: "Inter", sans-serif;
}
```

### **Advanced Configuration**
```css
@import "tailwindcss";

/* Custom utilities */
@utility {
  .scroll-smooth {
    scroll-behavior: smooth;
  }
}

/* Custom components */
@component {
  .btn {
    @apply px-4 py-2 rounded font-medium;
  }
  
  .btn-primary {
    @apply bg-blue-500 text-white hover:bg-blue-600;
  }
}
```

## **Migration Checklist**

### **Dependencies**
- ✅ Remove: `tailwindcss`, `@tailwindcss/postcss`, `autoprefixer`, `postcss`
- ✅ Install: `@tailwindcss/cli@next`, `@tailwindcss/vite@next`
- ✅ Keep: `tailwind-merge`, `class-variance-authority`, `clsx`

### **Files**
- ✅ Update: `src/index.css` - Use `@import "tailwindcss"`
- ✅ Update: `vite.config.ts` - Use `@tailwindcss/vite` plugin
- ✅ Delete: `postcss.config.js`, `tailwind.config.js`

### **Code Changes**
- ✅ All existing Tailwind classes work the same
- ✅ `tailwind-merge` still works for utility merging
- ✅ Custom CSS can be added alongside Tailwind

## **Benefits of v4**
- **Faster builds**: No PostCSS processing overhead
- **Simpler setup**: Fewer configuration files
- **Better performance**: Optimized CSS generation
- **Modern architecture**: Built for current web standards

## **Troubleshooting**

### **Build Errors**
```bash
# If you see PostCSS errors, ensure all PostCSS packages are removed
npm ls | grep postcss  # Should return nothing

# Clean install if needed
rm -rf node_modules package-lock.json
npm install
```

### **CSS Not Loading**
```css
/* Ensure correct import in src/index.css */
@import "tailwindcss";

/* NOT these old imports */
/* @tailwind base; */
/* @tailwind components; */
/* @tailwind utilities; */
```

### **Vite Plugin Issues**
```typescript
// Ensure correct plugin import
import tailwindcss from "@tailwindcss/vite";

// Add to plugins array
plugins: [react(), tailwindcss()]
```

## **Best Practices**
- **Test thoroughly**: Verify all Tailwind classes still work
- **Update incrementally**: Migrate one component at a time if needed
- **Monitor bundle size**: v4 should reduce overall CSS size
- **Use CSS-in-CSS**: Leverage v4's CSS-based configuration for themes