Migration Guide: Tailwind CSS v3 to v4 (CSS-First Configuration)
I'll provide you with a comprehensive migration guide and a working example that demonstrates Tailwind CSS v4's new CSS-first configuration approach.
Migration Steps Overview
- Installation Changes: Update package.json to use Tailwind v4
- Configuration Migration: Convert JS config to CSS-based config
-
Directive Changes: Update
@tailwindto@import "tailwindcss" - Theme Configuration: Move theme from JS to CSS custom properties
- Build Process: Adjust build commands for the new version
Here's a complete HTML example that demonstrates the new CSS-first approach:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Tailwind CSS v4 Migration Guide</title>
<script src="https://cdn.tailwindcss.com/v4-next"></script>
<style type="text/css">
/* New CSS-first configuration in Tailwind v4 */
@import "tailwindcss";
/* Custom theme configuration using CSS variables */
@theme {
--color-primary: #3b82f6;
--color-secondary: #f97316;
--color-accent: #8b5cf6;
--font-family-sans: ui-sans-serif, system-ui, sans-serif;
--font-family-display: ui-sans-serif, system-ui, sans-serif;
--breakpoint-md: 48rem;
--breakpoint-lg: 64rem;
--spacing-1: 0.25rem;
--spacing-2: 0.5rem;
--spacing-3: 0.75rem;
--spacing-4: 1rem;
--spacing-5: 1.25rem;
--spacing-6: 1.5rem;
--spacing-8: 2rem;
--spacing-10: 2.5rem;
--spacing-12: 3rem;
--spacing-16: 4rem;
--spacing-20: 5rem;
--spacing-24: 6rem;
}
/* Custom styles using the new theme variables */
.btn-primary {
background-color: var(--color-primary);
color: white;
padding: var(--spacing-3) var(--spacing-6);
border-radius: 0.375rem;
font-weight: 600;
transition: background-color 0.2s;
}
.btn-primary:hover {
background-color: color-mix(in srgb, var(--color-primary) 90%, black);
}
.card {
border-radius: 0.5rem;
box-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1);
padding: var(--spacing-6);
background: white;
}
</style>
</head>
<body class="bg-gray-50 font-sans">
<header class="bg-white shadow-sm">
<div class="container mx-auto px-4 py-6">
<h1 class="text-3xl font-bold text-gray-900">Tailwind CSS v4 Migration Guide</h1>
<p class="text-lg text-gray-600 mt-2">CSS-First Configuration Example</p>
</div>
</header>
<main class="container mx-auto px-4 py-12">
<section class="mb-12">
<h2 class="text-2xl font-semibold text-gray-800 mb-6">Key Changes in v4</h2>
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
<div class="card">
<h3 class="text-xl font-semibold text-primary mb-3">CSS-First Configuration</h3>
<p class="text-gray-700">Theme is now defined using CSS custom properties in a <code>@theme</code> block instead of a JavaScript configuration file.</p>
</div>
<div class="card">
<h3 class="text-xl font-semibold text-primary mb-3">New Directives</h3>
<p class="text-gray-700">The <code>@tailwind</code> directive is replaced with <code>@import "tailwindcss"</code> for base styles.</p>
</div>
<div class="card">
<h3 class="text-xl font-semibold text-primary mb-3">Performance Improvements</h3>
<p class="text-gray-700">v4 includes significant performance improvements with faster build times and smaller output CSS.</p>
</div>
</div>
</section>
<section class="mb-12">
<h2 class="text-2xl font-semibold text-gray-800 mb-6">Migration Steps</h2>
<div class="bg-gray-100 p-6 rounded-lg">
<ol class="list-decimal list-inside space-y-3">
<li class="text-gray-700"><strong>Update package.json:</strong> Change Tailwind dependency to <code>"tailwindcss": "^4.0.0"</code></li>
<li class="text-gray-700"><strong>Replace configuration:</strong> Convert <code>tailwind.config.js</code> to CSS custom properties in your main CSS file</li>
<li class="text-gray-700"><strong>Update directives:</strong> Change <code>@tailwind base</code> to <code>@import "tailwindcss/base"</code> etc.</li>
<li class="text-gray-700"><strong>Adjust build process:</strong> Update your build scripts to work with the new version</li>
</ol>
</div>
</section>
<section>
<h2 class="text-2xl font-semibold text-gray-800 mb-6">Example Components</h2>
<div class="grid grid-cols-1 md:grid-cols-2 gap-8">
<div>
<h3 class="text-xl font-semibold text-gray-700 mb-4">Buttons</h3>
<div class="space-y-4">
<button class="btn-primary">Primary Button</button>
<button class="bg-secondary text-white px-4 py-2 rounded font-semibold">Secondary Button</button>
<button class="border border-gray-300 px-4 py-2 rounded text-gray-700 hover:bg-gray-50">Outlined Button</button>
</div>
</div>
<div>
<h3 class="text-xl font-semibold text-gray-700 mb-4">Form Elements</h3>
<div class="space-y-4">
<input type="text" placeholder="Enter your name" class="w-full px-4 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-primary focus:border-transparent">
<select class="w-full px-4 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-primary focus:border-transparent">
<option>Option 1</option>
<option>Option 2</option>
<option>Option 3</option>
</select>
<div class="flex items-center">
<input type="checkbox" id="example-checkbox" class="h-4 w-4 text-primary focus:ring-primary border-gray-300 rounded">
<label for="example-checkbox" class="ml-2 block text-sm text-gray-700">Check this box</label>
</div>
</div>
</div>
</div>
</section>
</main>
<footer class="bg-gray-800 text-white mt-16 py-8">
<div class="container mx-auto px-4 text-center">
<p>Tailwind CSS v4 Migration Example</p>
<p class="mt-2 text-gray-400">This demo uses the new CSS-first configuration approach</p>
</div>
</footer>
</body>
</html>
Key Changes in Tailwind CSS v4
CSS-First Configuration: Instead of configuring Tailwind in a JavaScript file (tailwind.config.js), you now define your theme using CSS custom properties within a
@themeblock.New Import Syntax: The
@tailwinddirective is replaced with@import "tailwindcss"for base styles, components, and utilities.Simplified Setup: The build process is simplified with fewer dependencies required.
Performance: v4 is significantly faster with up to 10x faster build times in many cases.
Migration Steps in Detail
1. Update Your Dependencies
npm uninstall tailwindcss
npm install tailwindcss@next
2. Convert Your Configuration
Instead of a tailwind.config.js file, add your theme configuration to your main CSS file:
@import "tailwindcss";
@theme {
/* Convert your theme configuration here */
--color-primary: #3b82f6;
--color-secondary: #f97316;
/* Add other theme values as CSS custom properties */
}
3. Update Your Build Process
Adjust your build scripts to work with the new version. If you were using PostCSS, you might need to update your configuration.
4. Test Your Application
Thoroughly test your application to ensure all styles are working correctly with the new configuration.
This example demonstrates the new CSS-first approach while maintaining the utility-first philosophy that makes Tailwind powerful. The migration maintains backward compatibility for most utilities while offering a more flexible configuration system.
Top comments (0)