configuring-tailwind-v4

name	configuring-tailwind-v4
description	Configure Tailwind CSS v4 using Vite plugin, PostCSS, or CLI with CSS-first configuration via @import and @theme directives. Use when setting up new projects or migrating build tools. Use when this capability is needed.
metadata	{"author":"djankies"}

Configuring Tailwind v4

Purpose

Configure Tailwind CSS v4 using modern CSS-first configuration. Tailwind v4 eliminates JavaScript configuration files in favor of CSS-based setup using @import and @theme directives.

Installation Methods

Vite Projects (Recommended)

Step 1: Install Dependencies

npm install tailwindcss @tailwindcss/vite

Step 2: Configure Vite Plugin

Add the Tailwind plugin to vite.config.js:

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 in CSS

Create or update your main CSS file (e.g., src/index.css):

@import 'tailwindcss';

PostCSS Projects

Step 1: Install Dependencies

npm install tailwindcss @tailwindcss/postcss

Step 2: Configure PostCSS

Create postcss.config.js:

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Step 3: Import Tailwind in CSS

@import 'tailwindcss';

CLI Usage

Step 1: Install CLI

npm install tailwindcss @tailwindcss/cli

Step 2: Create Input CSS

@import 'tailwindcss';

Step 3: Run Build Command

npx @tailwindcss/cli -i input.css -o output.css --watch

CSS-First Configuration

Tailwind v4 uses the @theme directive for all customization:

@import 'tailwindcss';

@theme {
  --font-display: 'Satoshi', 'sans-serif';
  --font-body: 'Inter', 'sans-serif';

  --color-brand-primary: oklch(0.65 0.25 270);
  --color-brand-accent: oklch(0.75 0.22 320);

  --breakpoint-3xl: 120rem;
  --breakpoint-4xl: 160rem;

  --spacing-18: 4.5rem;
  --spacing-72: 18rem;

  --radius-4xl: 2rem;

  --shadow-brutal: 8px 8px 0 0 rgb(0 0 0);
}

Automatic Content Detection

Template files are discovered automatically using built-in heuristics. No content array configuration required. Files in .gitignore are automatically excluded.

Manual Source Control (when needed):

@import 'tailwindcss';

@source "../node_modules/@my-company/ui-lib";
@source "./legacy-components";

Exclude paths:

@source not "./legacy";
@source not "./docs";

Disable automatic detection:

@import 'tailwindcss' source(none);
@source "./src";

Key Differences from v3

v3	v4
tailwind.config.js	CSS @theme directive
@tailwind base;	@import 'tailwindcss';
content: [] array	Automatic detection
postcss-tailwindcss	@tailwindcss/postcss

Performance

• Full builds: 3.78x faster than v3
• Incremental rebuilds with new CSS: 8.8x faster
• Incremental rebuilds without new CSS: 182x faster

Browser Requirements

Tailwind v4 requires:

• Safari 16.4+
• Chrome 111+
• Firefox 128+

Projects requiring older browser support must stay on v3.4.

See Also

• references/vite-setup.md - Complete Vite configuration examples
• references/postcss-setup.md - PostCSS configuration patterns
• references/nextjs-setup.md - Next.js specific setup

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.