Migrating to Tailwind CSS v4: What You Need to Know

What's New in Tailwind v4

Tailwind CSS v4 brings significant changes to how we write and configure our styles. Let's explore what's new and how to migrate.

Major Changes

1. CSS-First Configuration

Configuration now lives in CSS:

@theme {

--color-primary-500: oklch(0.6 0.2 250);

--font-sans: 'Inter', sans-serif;

}

2. OKLCH Colors

Better color manipulation with OKLCH:

3. New Gradient Syntax

<div class="bg-linear-to-r from-primary-500 to-secondary-500">

Gradient content

</div>

4. Container Queries

Built-in container query support:

<div class="@container">

<div class="@md:flex @lg:grid">

Responsive to container

</div>

</div>

Migration Steps

Step 1: Update Dependencies

npm install tailwindcss@latest

Step 2: Convert Configuration

Move from tailwind.config.js to CSS-based config.

Step 3: Update Class Names

Some utilities have been renamed:

Step 4: Test Thoroughly

Common Issues

Issue 1: Missing Colors

Solution: Define colors in @theme block

Issue 2: Plugin Compatibility

Solution: Check for v4-compatible versions

Issue 3: Build Errors

Solution: Clear cache and rebuild

Conclusion

Tailwind v4 is a significant upgrade that modernizes the framework. Take time to migrate properly and enjoy the new features.