173 lines
4.1 KiB
Plaintext
173 lines
4.1 KiB
Plaintext
---
|
|
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
|