Setting Up Tailwind CSS 4.0: What Changed

Tailwind CSS 4.0 is a complete rewrite with a new engine that is 10x faster, a CSS-first configuration approach, and native cascade layers. Here is how to set it up in a new project and migrate from v3.

Installation

Install tailwindcss and the @tailwindcss/vite plugin (or @tailwindcss/postcss for non-Vite projects). In v4, the PostCSS plugin is no longer the default — the Vite plugin provides better performance with hot module replacement that updates styles without a full page reload.

CSS-First Configuration

The biggest change in v4 is moving configuration from tailwind.config.js to your CSS file. Instead of a JavaScript config object, you use @theme directive in your CSS to define colors, spacing, fonts, and other design tokens. This means your editor CSS tooling (autocomplete, linting) works with your Tailwind configuration natively.

Automatic Content Detection

V4 automatically detects which files to scan for class names — no more content array in the config. It uses your project file structure and framework conventions to find templates. You can still override this with @source directives in your CSS for edge cases.

Native Cascade Layers

V4 uses CSS @layer to organize base styles, components, and utilities. This eliminates specificity battles and makes it predictable which styles win when multiple utilities apply. Your custom CSS integrates cleanly by targeting the appropriate layer.

Migrating from v3

Run the official migration tool: npx @tailwindcss/upgrade. It converts your tailwind.config.js to CSS @theme directives, updates deprecated class names, and adjusts your build configuration. Most projects migrate in under 30 minutes. The migration tool handles the mechanical changes — review the output for any custom plugin or configuration that needs manual adjustment.