Tailwind CSS v4 - Complete Setup Guide

Introduction

Tailwind CSS v4 represents a significant evolution from previous versions, introducing a more streamlined, CSS-first approach to utility-first styling. Released in 2025, v4 comes with a completely rewritten engine called “Oxide” that brings major performance improvements and new features designed for the modern web. This guide will walk you through setting up and using Tailwind CSS v4 in different project environments.

Key Changes in v4

New High-Performance Engine: The “Oxide” engine delivers builds up to 5x faster for full builds and over 100x faster for incremental builds, with some operations measured in microseconds
No More Configuration Files: Unlike v3, Tailwind v4 no longer requires a tailwind.config.js file by default
CSS-First Configuration: Configuration happens directly in your CSS files using @theme directives
Automatic Content Detection: Tailwind automatically finds your template files without requiring content paths configuration
Unified Toolchain: Built-in import handling, vendor prefixing, and syntax transforms without additional tooling
Modern CSS Features: Built on native cascade layers, registered custom properties with @property, wide-gamut colors, and color-mix()
Simplified Installation: Different installation process for various frameworks with fewer dependencies

Basic Installation

The installation process for Tailwind CSS v4 is significantly simpler than previous versions, with fewer dependencies and steps required.

Step 1: Install Tailwind CSS

The installation process depends on your project framework:

For Vite Projects:

npm install tailwindcss @tailwindcss/vite

For Next.js:

npm install tailwindcss

Next.js 14+ automatically detects and processes Tailwind CSS without additional configuration.

For standalone projects (using CLI):

npm install @tailwindcss/cli -g

Browser Support Note

Tailwind CSS v4.0 is designed for modern browsers only and targets:

Safari 16.4+
Chrome 111+
Firefox 128+

If you need to support older browsers, it’s recommended to stick with Tailwind v3.4 until your browser support requirements change.

Step 2: Framework Integration

For Vite Projects:

In your vite.config.js file:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react' // Or your framework plugin
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(), // Or your framework plugin
    tailwindcss()
  ]
})

For Next.js:

Next.js 14+ automatically detects and processes Tailwind CSS without additional configuration.

Step 3: Add Tailwind to your CSS

In v4, you import Tailwind using a regular CSS @import statement, not the @tailwind directives used in v3.

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

@import "tailwindcss";

/* Optional theme customization */
@theme {
  --color-primary: #3b82f6;
  --color-secondary: #6b7280;
  --font-display: "Inter", sans-serif;
  --breakpoint-desktop: 1280px;
}

This is significantly different from the v3 approach, which required:

/* OLD v3 approach - DO NOT USE for v4 */
@tailwind base;
@tailwind components;
@tailwind utilities;

Step 4: Import CSS in your application

Make sure your CSS file is imported in your main application file:

// For React/Vite
import './index.css'

// For Next.js (typically this is already handled in _app.js or layout.js)

Customizing Tailwind v4

Theme Customization

In v4, you customize your theme directly in CSS using the @theme directive:

@import "tailwindcss";

@theme {
  /* Colors */
  --color-primary: #3b82f6;
  --color-primary-light: #60a5fa;
  --color-primary-dark: #2563eb;
  
  /* Typography */
  --font-sans: "Inter", ui-sans-serif, system-ui;
  --font-display: "Montserrat", sans-serif;
  
  /* Spacing */
  --spacing-xl: 2.5rem;
  --spacing-2xl: 4rem;
  
  /* Breakpoints */
  --breakpoint-desktop: 1280px;
  --breakpoint-large: 1536px;
}

Creating a Configuration File (Optional)

Although not required, you can still create a tailwind.config.js file for advanced customization:

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  // Only include advanced configuration options here
  // Basic theme customization should be in CSS
}

Using Tailwind CSS v4

Basic Usage

The utility classes in v4 work similarly to v3:

<div class="bg-primary text-white p-4 rounded-lg shadow-md">
  <h2 class="text-xl font-display font-bold">Hello Tailwind v4</h2>
  <p class="mt-2">This is styled with Tailwind CSS v4</p>
</div>

Using Custom Theme Variables

With your custom theme variables:

<div class="bg-[var(--color-primary)] text-white p-[var(--spacing-xl)]">
  Custom themed element
</div>

Responsive Design

Responsive design follows the same pattern as before:

<div class="w-full md:w-1/2 lg:w-1/3">
  Responsive width
</div>

Advanced Features

Automatic Content Detection

One of the most powerful features in Tailwind v4 is that it can automatically find your template files without requiring explicit content path configuration:

Using PostCSS or CLI: Tailwind crawls your project looking for template files using intelligent heuristics (like skipping directories in your .gitignore file)
Using the Vite plugin: Tailwind relies on the module graph to know exactly which files you’re actually using, ensuring maximum performance without false positives or negatives

CSS Variables for Dynamic Theming

:root {
  color-scheme: light;
}

@media (prefers-color-scheme: dark) {
  :root {
    color-scheme: dark;
  }
}

@theme {
  light: {
    --color-background: white;
    --color-text: #111827;
  }
  dark: {
    --color-background: #111827;
    --color-text: white;
  }
}

Container Queries

Tailwind v4 adds support for container queries directly in the core framework:

<div class="@container">
  <div class="@lg:text-xl @2xl:text-2xl">
    This text changes size based on the container width
  </div>
</div>

You can use @min-* and @max-* variants to support container query ranges.

Using Plugins

// In your optional tailwind.config.js
import typography from '@tailwindcss/typography'

export default {
  plugins: [
    typography
  ]
}

Framework-Specific Setup Examples

React + Vite

# Create a new project
npm create vite@latest my-tailwind-app -- --template react

# Navigate to project
cd my-tailwind-app

# Install dependencies
npm install
npm install tailwindcss @tailwindcss/vite

Update vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

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

Create or update src/index.css:

@import "tailwindcss";

Next.js

# Create a new project
npx create-next-app@latest my-nextjs-tailwind

# Navigate to project
cd my-nextjs-tailwind

# Install tailwindcss
npm install tailwindcss

Create or update app/globals.css:

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
}

Troubleshooting

Common Issues and Solutions

“Could not determine executable to run” error
- This is normal in v4 as the init command is removed
- Follow the framework-specific installation guides instead
Classes not applying correctly
- Ensure your CSS import is properly set up
- Check that your content paths are correctly configured (if using a config file)
IDE intellisense not working
- Make sure you have the latest Tailwind CSS IntelliSense extension
- You might need to manually create a minimal tailwind.config.js file for better IDE support
Conflict with v3 projects
- Keep projects separated or specify versions explicitly
- Use tailwindcss@3 for older projects

Migration from v3 to v4

There are significant changes between v3 and v4, but Tailwind provides tools to simplify the migration process.

Automated Upgrade Tool

Tailwind provides an official upgrade tool that automates much of the migration process:

npx @tailwindcss/upgrade@latest

This tool helps with:

Updating your dependencies
Migrating your configuration file to CSS
Handling changes to your template files

The upgrade tool requires Node.js 20 or higher.

Manual Migration Key Steps

If you prefer to migrate manually:

Update your installation:

npm uninstall tailwindcss postcss autoprefixer
npm install tailwindcss

If using Vite, switch to the dedicated plugin:
```
npm install @tailwindcss/vite
```

Update your CSS imports:

/* Replace this v3 approach */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* With this v4 approach */
@import "tailwindcss";

Move theme configuration from tailwind.config.js to CSS:

@import "tailwindcss";

@theme {
  /* Move your theme settings here */
}

Update class names that have changed in v4 (like renamed utilities)
Remove any utilities that were deprecated and removed in v4

Troubleshooting v4-Specific Issues

“Could not determine executable to run” error

This is a common error when trying to run npx tailwindcss init in Tailwind v4. The reason is that the init command no longer exists in v4 since there’s no need for a tailwind.config.js file by default.

Solution: Follow the framework-specific installation guides and skip the initialization step. If you need a configuration file for advanced customization, create it manually.

Classes not applying correctly

Ensure your CSS import is properly set up with @import "tailwindcss";
Make sure your framework integration is correctly configured
Check that you’re not using deprecated or renamed utilities

IDE intellisense not working

Update your Tailwind CSS IntelliSense extension to the latest version
You might need to manually create a minimal tailwind.config.js file for better IDE support

Resources

Conclusion

Tailwind CSS v4 represents a major advancement with its Oxide engine bringing dramatic performance improvements and a completely reimagined developer experience. The CSS-first approach, automatic content detection, and unified toolchain make it easier than ever to integrate Tailwind into your projects. While it requires modern browsers, the simplified configuration, improved performance, and enhanced features make it a compelling upgrade for new and existing projects alike.