Tailwind CSS v4: CSS-First Configuration, Vite Plugin, and Zero-Config Dark Mode

Tailwind CSS v4 is a ground-up rewrite of the framework's engine. It delivers 5× faster full builds and 100× faster incremental builds versus v3, drops the JavaScript config file entirely in favour of CSS, and ships a native Vite plugin that replaces the PostCSS pipeline.

>Installation — Vite

bash

npm install tailwindcss@4 @tailwindcss/vite

# No PostCSS, no tailwind.config.js, no content array

TypeScript

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

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

CSS

/* globals.css — one line is all you need */
@import "tailwindcss";

>CSS-first configuration with @theme inline

Design tokens are now defined directly in CSS using the @theme directive. All tokens automatically generate utility classes.

CSS

@import "tailwindcss";

@theme inline {
  /* Custom colours — generates bg-brand-*, text-brand-*, etc. */
  --color-brand-50:  #ecfeff;
  --color-brand-500: #06b6d4;
  --color-brand-900: #164e63;

  /* Custom font */
  --font-sans: 'Inter Variable', ui-sans-serif, system-ui;
  --font-mono: 'JetBrains Mono', ui-monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;

  /* Custom breakpoint */
  --breakpoint-3xl: 1920px;

  /* Custom animation */
  --animate-fade-up: fade-up 0.5s ease-out forwards;
}

@keyframes fade-up {
  from { opacity: 0; transform: translateY(12px); }
  to   { opacity: 1; transform: translateY(0); }
}

>Dark mode with @custom-variant

⚠ BREAKINGTailwind v4 does not support darkMode: 'class' in a config file — there is no config file. Declare the variant in CSS.

CSS

@import "tailwindcss";

/* Class-based dark mode */
@custom-variant dark (&:where(.dark, .dark *));

/* Media-query dark mode (alternative) */
@custom-variant dark (&:where(@media (prefers-color-scheme: dark)));

/* Usage — same Tailwind class syntax */
/* <div class="bg-white dark:bg-zinc-900"> */

>@source — include paths manually

Tailwind v4 auto-detects content. For files outside the default scan path (e.g. a monorepo package), add them with @source.

CSS

@import "tailwindcss";

/* Scan additional directories for class names */
@source "../../packages/ui/src/**/*.tsx";
@source "../node_modules/@company/design-system/dist/**/*.js";

>Migrate from v3

bash

# Automated upgrade tool
npx @tailwindcss/upgrade@4

# What it does:
# ✓ Removes tailwind.config.js (migrates to CSS @theme)
# ✓ Updates postcss.config.js → vite.config.ts plugin (if using Vite)
# ✓ Renames deprecated utility classes:
#   shadow-sm → shadow-xs, ring-0 → ring-none, etc.
# ✓ Moves @apply directives to equivalent v4 syntax
# ✓ Converts darkMode config → @custom-variant

>Notable utility changes

CSS

/* v3 → v4 renamed utilities */
shadow-sm    → shadow-xs
shadow       → shadow-sm
ring-0       → ring-none
blur         → blur-sm
drop-shadow  → drop-shadow-sm
/* Add the old name back via @utility if needed */
@utility shadow { box-shadow: var(--shadow-sm); }

NOTETailwind v4 requires Node.js 18+ and a bundler (Vite, webpack 5+, Parcel 2+, or esbuild). The PostCSS plugin is still available as @tailwindcss/postcss for non-Vite setups.