Mastering Tailwind CSS v4: What Developers Need to Know

Tailwind CSS v4 is a complete rewrite built for speed and simplicity. Powered by the new oxide engine written in Rust, builds are now up to 10x faster.

---

What Is New in Tailwind v4?

1. CSS-First Configuration

Say goodbye to complex tailwind.config.js files. In v4, configuration lives directly inside your CSS file using the @theme directive:

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --font-display: 'Inter', sans-serif;
}

2. Automatic Content Detection

Tailwind v4 automatically scans your project files for class names without requiring explicit content globs.

3. Container Queries Out-of-the-Box

Container queries are now native utility classes:

<div class="@container">
  <div class="@sm:grid-cols-2 grid grid-cols-1 gap-4">
    <!-- Card Content -->
  </div>
</div>

---

Upgrading to Tailwind v4

Upgrading is straightforward using the automated migration tool:

npx @tailwindcss/upgrade@next

Embrace the modern CSS era with cleaner configurations and lightning-fast builds!

Migration from Tailwind v3

Tailwind provides an automated migration tool that converts most v3 configuration to v4 format:

npx @tailwindcss/upgrade@next

Key breaking changes:

• tailwind.config.js is replaced by @theme in CSS
• @apply works but is now discouraged for complex utility chains
• JIT mode is the only mode; the full-class scanner is removed
• Arbitrary values syntax is unchanged: w-[42px] still works

CSS-First Theme Configuration

All design tokens live in CSS, giving you autocomplete in editors and direct access in regular CSS files:

@import "tailwindcss";

@theme {
  /* Custom colour palette */
  --color-brand: oklch(60% 0.2 250);
  --color-brand-dark: oklch(40% 0.2 250);

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

  /* Spacing overrides */
  --spacing-18: 4.5rem;
}

Access these tokens anywhere in your CSS:

.hero {
  background: var(--color-brand);
  font-family: var(--font-sans);
  padding-top: var(--spacing-18);
}

Container Queries

Container queries let components respond to their own size rather than the viewport:

<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 gap-6">
    <article>...</article>
    <article>...</article>
    <article>...</article>
  </div>
</div>

The outer div becomes the container. @sm: and @lg: are breakpoints relative to that container’s width — not the viewport.

Performance with the Oxide Engine

Tailwind v4’s Rust-powered Oxide engine provides:

• Full rebuild: ~5× faster than v3
• Incremental rebuild: ~100× faster than v3 (typically < 5 ms)
• Automatic content scanning: No content glob configuration needed; Oxide detects all template files

Benchmark from Tailwind’s release notes: a typical project that took 3.5 s to build in v3 takes under 400 ms in v4.

Using with Vite and Astro

npm install tailwindcss @tailwindcss/vite

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

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

Then import Tailwind in your global CSS file:

/* src/styles/global.css */
@import "tailwindcss";

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

Common Migration Issues

v3 Syntax	v4 Equivalent
bg-opacity-50	bg-black/50
ring-offset-2	Use shadow composition
overflow-ellipsis	text-ellipsis
flex-shrink-0	shrink-0
transform (explicit)	Removed; transforms apply automatically