Skip to content

tailwind-v4-vite.instructions.md

Latest commit

 

History

History
243 lines (174 loc) · 5.64 KB

tailwind-v4-vite.instructions.md

File metadata and controls

243 lines (174 loc) · 5.64 KB
description Tailwind CSS v4+ installation and configuration for Vite projects using the official @tailwindcss/vite plugin
applyTo 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