Tailwind CSS v4: What Changed and How to Upgrade

Tailwind CSS v4 is a ground-up rewrite. The biggest change for day-to-day work: configuration moves from tailwind.config.js into your CSS file.

Install with Vite

npm install tailwindcss @tailwindcss/vite

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

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

/* src/styles.css - this one line replaces the three @tailwind directives */
@import "tailwindcss";

Other setups can use @tailwindcss/postcss or the @tailwindcss/cli package.

CSS-first configuration

@import "tailwindcss";

@theme {
  --color-brand-500: oklch(0.62 0.15 190);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

Each theme variable creates utilities (bg-brand-500, font-display, 3xl:) and is available as a normal CSS variable: var(--color-brand-500).

Other notable changes

• Automatic content detection - no content array; your source files are found automatically (and .gitignored files are skipped).
• Faster builds, especially incremental rebuilds.
• Modern CSS under the hood: cascade layers, @property, color-mix(), and a default palette defined in OKLCH.
• Container queries built in: @container and @md: variants without a plugin.
• Custom utilities with @utility and variants with @custom-variant.

Upgrading a v3 project

npx @tailwindcss/upgrade

The upgrade tool rewrites your config, CSS and many renamed classes. Review the diff, then check a few pages visually: some defaults changed (for example border colour and ring width). v4 targets modern browsers, so check your support requirements before upgrading.