/tailwind-best-practices

Why It Matters

Tailwind CSS v4 ships as a dedicated Vite plugin (@tailwindcss/vite) or PostCSS plugin (@tailwindcss/postcss). The old tailwindcss + postcss + autoprefixer setup no longer applies. Configuration moves entirely out of JavaScript and into CSS via @import "tailwindcss".

Incorrect

# ❌ v3 install — wrong for v4
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

// ❌ v3 postcss.config.js — not needed in v4 with Vite
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

/* ❌ v3 directives — do not use in v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

Correct

With Vite (recommended)

npm install tailwindcss @tailwindcss/vite

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

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

/* app.css — single import replaces all three @tailwind directives */
@import "tailwindcss";

With PostCSS (Laravel Mix, Webpack, etc.)

npm install tailwindcss @tailwindcss/postcss

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

/* app.css */
@import "tailwindcss";

Limiting scan scope with @source

By default, v4 auto-detects your template files. Override with @source if needed:

@import "tailwindcss";

/* Only scan specific paths */
@source "./resources/js/**/*.{ts,tsx}";
@source "./resources/views/**/*.blade.php";

/* Exclude paths from scanning */
@source not "./resources/js/legacy/**";

Importing without emitting CSS with @reference

Use @reference when you need access to theme values or @apply in a secondary CSS file without duplicating Tailwind's output:

/* components/card.css — not the main entry point */
@reference "tailwindcss";

.card {
  @apply rounded-lg bg-white shadow-sm dark:bg-gray-800;
}

Recommended Patterns

Reference: https://tailwindcss.com/docs/installation