awesome-copilot/instructions/tailwind-v4-vite.instructions.md

description, applyTo

description	applyTo
Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin	vite.config.ts, vite.config.js, **/*.css, **/*.tsx, **/*.ts, **/*.jsx, **/*.js

Tailwind CSS v4+ Installation with Vite

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.

Key Changes in Tailwind CSS v4

• No PostCSS configuration required when using the Vite plugin
• No tailwind.config.js required - configuration is done via CSS
• New @tailwindcss/vite plugin replaces the PostCSS-based approach
• CSS-first configuration using @theme directive
• Automatic content detection - no need to specify content paths

Installation Steps

Step 1: Install Dependencies

Install tailwindcss and the @tailwindcss/vite plugin:

npm install tailwindcss @tailwindcss/vite

Step 2: Configure Vite Plugin

Add the @tailwindcss/vite plugin to your Vite configuration file:

// vite.config.ts
import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'

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

For React projects with Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

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

Step 3: Import Tailwind CSS

Add the Tailwind CSS import to your main CSS file (e.g., src/index.css or src/App.css):

@import "tailwindcss";

Step 4: Verify CSS Import in Entry Point

Ensure your main CSS file is imported in your application entry point:

// src/main.tsx or src/main.ts
import './index.css'

Step 5: Start Development Server

Run the development server to verify installation:

npm run dev

What NOT to Do in Tailwind v4

Do NOT Create tailwind.config.js

Tailwind v4 uses CSS-first configuration. Do not create a tailwind.config.js file unless you have specific legacy requirements.

// ❌ NOT NEEDED in Tailwind v4
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
}

Do NOT Create postcss.config.js for Tailwind

When using the @tailwindcss/vite plugin, PostCSS configuration for Tailwind is not required.

// ❌ NOT NEEDED when using @tailwindcss/vite
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Do NOT Use Old Directives

The old @tailwind directives are replaced by a single import:

/* ❌ OLD - Do not use in Tailwind v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* ✅ NEW - Use this in Tailwind v4 */
@import "tailwindcss";

CSS-First Configuration (Tailwind v4)

Custom Theme Configuration

Use the @theme directive in your CSS to customize your design tokens:

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --font-sans: 'Inter', system-ui, sans-serif;
  --radius-lg: 0.75rem;
}

Adding Custom Utilities

Define custom utilities directly in CSS:

@import "tailwindcss";

@utility content-auto {
  content-visibility: auto;
}

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

Adding Custom Variants

Define custom variants in CSS:

@import "tailwindcss";

@variant hocus (&:hover, &:focus);
@variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);

Verification Checklist

After installation, verify:

• tailwindcss and @tailwindcss/vite are in package.json dependencies
• vite.config.ts includes the tailwindcss() plugin
• Main CSS file contains @import "tailwindcss";
• CSS file is imported in the application entry point
• Development server runs without errors
• Tailwind utility classes (e.g., text-blue-500, p-4) render correctly

Example Usage

Test the installation with a simple component:

export function TestComponent() {
  return (
    <div className="min-h-screen bg-gray-100 flex items-center justify-center">
      <h1 className="text-3xl font-bold text-blue-600 underline">
        Hello, Tailwind CSS v4!
      </h1>
    </div>
  )
}

Troubleshooting

Styles Not Applying

1. Verify CSS import statement is @import "tailwindcss"; (not old directives)
2. Ensure CSS file is imported in your entry point
3. Check Vite config includes the tailwindcss() plugin
4. Clear Vite cache: rm -rf node_modules/.vite && npm run dev

Plugin Not Found Error

If you see "Cannot find module '@tailwindcss/vite'":

npm install @tailwindcss/vite

TypeScript Errors

If TypeScript cannot find types for the Vite plugin, ensure you have the correct import:

import tailwindcss from '@tailwindcss/vite'

Migration from Tailwind v3

If migrating from Tailwind v3:

1. Remove tailwind.config.js (move customizations to CSS @theme)
2. Remove postcss.config.js (if only used for Tailwind)
3. Uninstall old packages: npm uninstall postcss autoprefixer
4. Install new packages: npm install tailwindcss @tailwindcss/vite
5. Replace @tailwind directives with @import "tailwindcss";
6. Update Vite config to use @tailwindcss/vite plugin

Reference

• Official Documentation: https://tailwindcss.com/docs/installation/using-vite
• Tailwind CSS v4 Upgrade Guide: https://tailwindcss.com/docs/upgrade-guide