How to set up Tailwind CSS v4

What changed in Tailwind CSS v4

Tailwind CSS v4 is a ground-up rewrite with a much faster engine, but the change you'll feel first is configuration: it's now CSS-first. There's no tailwind.config.js to scaffold, no @tailwind directives, and no content array to maintain — Tailwind detects your template files automatically. If you're maintaining an existing v3 project, see the v3 guide; this article covers a fresh v4 setup.

The three big day-to-day differences from v3:

1. You import Tailwind with a single line — @import "tailwindcss"; — instead of the old @tailwind base; @tailwind components; @tailwind utilities;.
2. Configuration lives in your CSS via the @theme directive, not in a JavaScript config file.
3. Content/template detection is automatic, so there's no content: [...] to keep in sync.

Installing Tailwind v4

Pick the path that matches your build tooling. The Vite plugin is the recommended option; there's also a PostCSS plugin and a standalone CLI.

With Vite (recommended)

npm install tailwindcss @tailwindcss/vite

Add the plugin to your Vite config:

import { defineConfig } from 'vite';
import tailwindcss from '@tailwindcss/vite';

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

Then add a single import to your main CSS file (e.g. src/style.css):

@import "tailwindcss";

That's the entire setup — no config file, no directives, no content array. Start your dev server and utility classes just work.

With PostCSS

If you're using PostCSS directly (or a framework wired to it), install the PostCSS plugin instead:

npm install tailwindcss @tailwindcss/postcss

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

Your CSS entry point is the same single line: @import "tailwindcss";.

With the standalone CLI

No build tool at all? Use the CLI to compile and watch:

npm install @tailwindcss/cli
npx @tailwindcss/cli -i ./src/style.css -o ./dist/style.css --watch

Where src/style.css contains @import "tailwindcss";, and you link the compiled dist/style.css in your HTML as usual.

Customizing your theme (CSS-first config)

In v4 you define design tokens directly in CSS with the @theme directive instead of editing a JavaScript object. Each token both generates utilities and is exposed as a real CSS variable at runtime:

@import "tailwindcss";

@theme {
  --color-brand: #1e40af;
  --font-display: "Inter", sans-serif;
}

The example above gives you utilities like bg-brand, text-brand, and font-display, and you can also use var(--color-brand) in hand-written CSS. If you'd rather keep a JavaScript config, you can still point to one explicitly with @config "./tailwind.config.js";.

Migrating from v3

Tailwind ships an automated upgrade tool. Run it on a clean git branch so you can review the diff:

npx @tailwindcss/upgrade

The main manual changes it applies, if you prefer to do them by hand:

1. Replace @tailwind base; @tailwind components; @tailwind utilities; with a single @import "tailwindcss";.
2. Move values from tailwind.config.js into an @theme block (or keep the file via @config).
3. Swap the old PostCSS plugin for @tailwindcss/postcss, or move to the Vite plugin.
4. Update any renamed/removed deprecated utilities the tool flags.

A note on browser support

v4 leans on modern CSS features (cascade layers, @property, color-mix()), so it targets recent browsers — roughly Safari 16.4+, Chrome 111+, and Firefox 128+. If you must support older browsers, stay on Tailwind v3.

For quick experiments without any local setup, Tailwind Play runs the latest version in the browser. For anything real, use one of the build setups above.