|
| 1 | +--- |
| 2 | +description: 'Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin' |
| 3 | +applyTo: 'vite.config.ts, vite.config.js, **/*.css, **/*.tsx, **/*.ts, **/*.jsx, **/*.js' |
| 4 | +--- |
| 5 | + |
| 6 | +# Tailwind CSS v4+ Installation with Vite |
| 7 | + |
| 8 | +Instructions for installing and configuring Tailwind CSS version 4 and above using the official Vite plugin. Tailwind CSS v4 introduces a simplified setup that eliminates the need for PostCSS configuration and tailwind.config.js in most cases. |
| 9 | + |
| 10 | +## Key Changes in Tailwind CSS v4 |
| 11 | + |
| 12 | +- **No PostCSS configuration required** when using the Vite plugin |
| 13 | +- **No tailwind.config.js required** - configuration is done via CSS |
| 14 | +- **New @tailwindcss/vite plugin** replaces the PostCSS-based approach |
| 15 | +- **CSS-first configuration** using `@theme` directive |
| 16 | +- **Automatic content detection** - no need to specify content paths |
| 17 | + |
| 18 | +## Installation Steps |
| 19 | + |
| 20 | +### Step 1: Install Dependencies |
| 21 | + |
| 22 | +Install `tailwindcss` and the `@tailwindcss/vite` plugin: |
| 23 | + |
| 24 | +```bash |
| 25 | +npm install tailwindcss @tailwindcss/vite |
| 26 | +``` |
| 27 | + |
| 28 | +### Step 2: Configure Vite Plugin |
| 29 | + |
| 30 | +Add the `@tailwindcss/vite` plugin to your Vite configuration file: |
| 31 | + |
| 32 | +```typescript |
| 33 | +// vite.config.ts |
| 34 | +import { defineConfig } from 'vite' |
| 35 | +import tailwindcss from '@tailwindcss/vite' |
| 36 | + |
| 37 | +export default defineConfig({ |
| 38 | + plugins: [ |
| 39 | + tailwindcss(), |
| 40 | + ], |
| 41 | +}) |
| 42 | +``` |
| 43 | + |
| 44 | +For React projects with Vite: |
| 45 | + |
| 46 | +```typescript |
| 47 | +// vite.config.ts |
| 48 | +import { defineConfig } from 'vite' |
| 49 | +import react from '@vitejs/plugin-react' |
| 50 | +import tailwindcss from '@tailwindcss/vite' |
| 51 | + |
| 52 | +export default defineConfig({ |
| 53 | + plugins: [ |
| 54 | + react(), |
| 55 | + tailwindcss(), |
| 56 | + ], |
| 57 | +}) |
| 58 | +``` |
| 59 | + |
| 60 | +### Step 3: Import Tailwind CSS |
| 61 | + |
| 62 | +Add the Tailwind CSS import to your main CSS file (e.g., `src/index.css` or `src/App.css`): |
| 63 | + |
| 64 | +```css |
| 65 | +@import "tailwindcss"; |
| 66 | +``` |
| 67 | + |
| 68 | +### Step 4: Verify CSS Import in Entry Point |
| 69 | + |
| 70 | +Ensure your main CSS file is imported in your application entry point: |
| 71 | + |
| 72 | +```typescript |
| 73 | +// src/main.tsx or src/main.ts |
| 74 | +import './index.css' |
| 75 | +``` |
| 76 | + |
| 77 | +### Step 5: Start Development Server |
| 78 | + |
| 79 | +Run the development server to verify installation: |
| 80 | + |
| 81 | +```bash |
| 82 | +npm run dev |
| 83 | +``` |
| 84 | + |
| 85 | +## What NOT to Do in Tailwind v4 |
| 86 | + |
| 87 | +### Do NOT Create tailwind.config.js |
| 88 | + |
| 89 | +Tailwind v4 uses CSS-first configuration. Do not create a `tailwind.config.js` file unless you have specific legacy requirements. |
| 90 | + |
| 91 | +```javascript |
| 92 | +// ❌ NOT NEEDED in Tailwind v4 |
| 93 | +module.exports = { |
| 94 | + content: ['./src/**/*.{js,ts,jsx,tsx}'], |
| 95 | + theme: { |
| 96 | + extend: {}, |
| 97 | + }, |
| 98 | + plugins: [], |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +### Do NOT Create postcss.config.js for Tailwind |
| 103 | + |
| 104 | +When using the `@tailwindcss/vite` plugin, PostCSS configuration for Tailwind is not required. |
| 105 | + |
| 106 | +```javascript |
| 107 | +// ❌ NOT NEEDED when using @tailwindcss/vite |
| 108 | +module.exports = { |
| 109 | + plugins: { |
| 110 | + tailwindcss: {}, |
| 111 | + autoprefixer: {}, |
| 112 | + }, |
| 113 | +} |
| 114 | +``` |
| 115 | + |
| 116 | +### Do NOT Use Old Directives |
| 117 | + |
| 118 | +The old `@tailwind` directives are replaced by a single import: |
| 119 | + |
| 120 | +```css |
| 121 | +/* ❌ OLD - Do not use in Tailwind v4 */ |
| 122 | +@tailwind base; |
| 123 | +@tailwind components; |
| 124 | +@tailwind utilities; |
| 125 | + |
| 126 | +/* ✅ NEW - Use this in Tailwind v4 */ |
| 127 | +@import "tailwindcss"; |
| 128 | +``` |
| 129 | + |
| 130 | +## CSS-First Configuration (Tailwind v4) |
| 131 | + |
| 132 | +### Custom Theme Configuration |
| 133 | + |
| 134 | +Use the `@theme` directive in your CSS to customize your design tokens: |
| 135 | + |
| 136 | +```css |
| 137 | +@import "tailwindcss"; |
| 138 | + |
| 139 | +@theme { |
| 140 | + --color-primary: #3b82f6; |
| 141 | + --color-secondary: #64748b; |
| 142 | + --font-sans: 'Inter', system-ui, sans-serif; |
| 143 | + --radius-lg: 0.75rem; |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +### Adding Custom Utilities |
| 148 | + |
| 149 | +Define custom utilities directly in CSS: |
| 150 | + |
| 151 | +```css |
| 152 | +@import "tailwindcss"; |
| 153 | + |
| 154 | +@utility content-auto { |
| 155 | + content-visibility: auto; |
| 156 | +} |
| 157 | + |
| 158 | +@utility scrollbar-hidden { |
| 159 | + scrollbar-width: none; |
| 160 | + &::-webkit-scrollbar { |
| 161 | + display: none; |
| 162 | + } |
| 163 | +} |
| 164 | +``` |
| 165 | + |
| 166 | +### Adding Custom Variants |
| 167 | + |
| 168 | +Define custom variants in CSS: |
| 169 | + |
| 170 | +```css |
| 171 | +@import "tailwindcss"; |
| 172 | + |
| 173 | +@variant hocus (&:hover, &:focus); |
| 174 | +@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &); |
| 175 | +``` |
| 176 | + |
| 177 | +## Verification Checklist |
| 178 | + |
| 179 | +After installation, verify: |
| 180 | + |
| 181 | +- [ ] `tailwindcss` and `@tailwindcss/vite` are in `package.json` dependencies |
| 182 | +- [ ] `vite.config.ts` includes the `tailwindcss()` plugin |
| 183 | +- [ ] Main CSS file contains `@import "tailwindcss";` |
| 184 | +- [ ] CSS file is imported in the application entry point |
| 185 | +- [ ] Development server runs without errors |
| 186 | +- [ ] Tailwind utility classes (e.g., `text-blue-500`, `p-4`) render correctly |
| 187 | + |
| 188 | +## Example Usage |
| 189 | + |
| 190 | +Test the installation with a simple component: |
| 191 | + |
| 192 | +```tsx |
| 193 | +export function TestComponent() { |
| 194 | + return ( |
| 195 | + <div className="min-h-screen bg-gray-100 flex items-center justify-center"> |
| 196 | + <h1 className="text-3xl font-bold text-blue-600 underline"> |
| 197 | + Hello, Tailwind CSS v4! |
| 198 | + </h1> |
| 199 | + </div> |
| 200 | + ) |
| 201 | +} |
| 202 | +``` |
| 203 | + |
| 204 | +## Troubleshooting |
| 205 | + |
| 206 | +### Styles Not Applying |
| 207 | + |
| 208 | +1. Verify CSS import statement is `@import "tailwindcss";` (not old directives) |
| 209 | +2. Ensure CSS file is imported in your entry point |
| 210 | +3. Check Vite config includes the `tailwindcss()` plugin |
| 211 | +4. Clear Vite cache: `rm -rf node_modules/.vite && npm run dev` |
| 212 | + |
| 213 | +### Plugin Not Found Error |
| 214 | + |
| 215 | +If you see "Cannot find module '@tailwindcss/vite'": |
| 216 | + |
| 217 | +```bash |
| 218 | +npm install @tailwindcss/vite |
| 219 | +``` |
| 220 | + |
| 221 | +### TypeScript Errors |
| 222 | + |
| 223 | +If TypeScript cannot find types for the Vite plugin, ensure you have the correct import: |
| 224 | + |
| 225 | +```typescript |
| 226 | +import tailwindcss from '@tailwindcss/vite' |
| 227 | +``` |
| 228 | + |
| 229 | +## Migration from Tailwind v3 |
| 230 | + |
| 231 | +If migrating from Tailwind v3: |
| 232 | + |
| 233 | +1. Remove `tailwind.config.js` (move customizations to CSS `@theme`) |
| 234 | +2. Remove `postcss.config.js` (if only used for Tailwind) |
| 235 | +3. Uninstall old packages: `npm uninstall postcss autoprefixer` |
| 236 | +4. Install new packages: `npm install tailwindcss @tailwindcss/vite` |
| 237 | +5. Replace `@tailwind` directives with `@import "tailwindcss";` |
| 238 | +6. Update Vite config to use `@tailwindcss/vite` plugin |
| 239 | + |
| 240 | +## Reference |
| 241 | + |
| 242 | +- Official Documentation: https://tailwindcss.com/docs/installation/using-vite |
| 243 | +- Tailwind CSS v4 Upgrade Guide: https://tailwindcss.com/docs/upgrade-guide |
0 commit comments