Tailwind CSS 4: A Major Leap Forward
Tailwind CSS 4 features represent the biggest architectural change since the framework’s inception. The new Oxide engine, written in Rust, delivers 10x faster builds. Configuration moves from JavaScript to CSS. Content detection becomes automatic. These changes make Tailwind significantly simpler while maintaining the utility-first approach developers love.
This guide covers what is new, what has changed, and how to migrate from Tailwind CSS 3. Whether you are starting a new project or upgrading an existing one, you will understand the practical impact of every major change.
The Oxide Engine
Tailwind CSS 4 replaces the Node.js-based engine with Oxide, written in Rust. The result is dramatically faster builds:
Build Performance Comparison (large project, 50K+ utility usages):
┌──────────────────┬─────────────┬─────────────┐
│ Metric │ Tailwind v3 │ Tailwind v4 │
├──────────────────┼─────────────┼─────────────┤
│ Initial Build │ 380ms │ 35ms │
│ Incremental │ 85ms │ 5ms │
│ Full Rebuild │ 420ms │ 42ms │
│ Memory Usage │ 120MB │ 18MB │
└──────────────────┴─────────────┴─────────────┘
CSS-First Configuration
The most visible change in Tailwind CSS 4 is moving configuration from tailwind.config.js to your CSS file. Moreover, this makes configuration more portable and eliminates the need for a separate JavaScript config file:
/* app.css — Tailwind CSS 4 configuration */
@import "tailwindcss";
/* Custom theme values */
@theme {
--color-primary: #0891b2;
--color-primary-dark: #0e7490;
--color-surface: #0B1121;
--color-surface-light: #1e293b;
--color-text: #e2e8f0;
--color-text-muted: #94a3b8;
/* Custom spacing */
--spacing-18: 4.5rem;
--spacing-88: 22rem;
/* Custom fonts */
--font-mono: "JetBrains Mono", monospace;
--font-sans: "Inter", sans-serif;
/* Custom breakpoints */
--breakpoint-xs: 475px;
/* Custom animations */
--animate-fade-in: fade-in 0.5s ease-out;
@keyframes fade-in {
from { opacity: 0; transform: translateY(10px); }
to { opacity: 1; transform: translateY(0); }
}
}
/* Use the theme values as utilities */
/* bg-primary, text-text-muted, font-mono all work automatically */
Zero-Config Content Detection
Tailwind CSS 4 automatically detects which files to scan for class names. No more configuring the content array — it just works:
/* v3: Required manual content configuration */
/* tailwind.config.js
module.exports = {
content: [
'./src/**/*.{js,jsx,ts,tsx}',
'./index.html',
],
}
*/
/* v4: Automatic — scans all files in your project */
/* Just import and go */
@import "tailwindcss";
/* Exclude specific directories if needed */
@source not "./node_modules";
@source not "./vendor";
New Utilities and Variants
<!-- New container query support (built-in) -->
<div class="@container">
<div class="@sm:flex @md:grid @lg:grid-cols-3">
<!-- Responds to container width, not viewport -->
</div>
</div>
<!-- New starting-style for entry animations -->
<dialog class="open:animate-fade-in starting:opacity-0">
<!-- Animates on open -->
</dialog>
<!-- New color-mix for opacity -->
<div class="bg-primary/50">
<!-- 50% opacity primary color using CSS color-mix -->
</div>
<!-- New field-sizing for auto-growing textareas -->
<textarea class="field-sizing-content min-h-20 max-h-60">
<!-- Auto-grows with content -->
</textarea>
<!-- New inert variant -->
<div class="inert:opacity-50 inert:pointer-events-none">
<!-- Styles for inert elements -->
</div>
Migration from Tailwind CSS 3
Tailwind provides an automated upgrade tool that handles most changes:
# Automated migration
npx @tailwindcss/upgrade
# What it does:
# 1. Converts tailwind.config.js to @theme in CSS
# 2. Updates @tailwind directives to @import
# 3. Renames changed utilities
# 4. Removes content configuration
# 5. Updates PostCSS config
Manual Changes Required
/* Before (v3) */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* After (v4) */
@import "tailwindcss";
/* Before: @apply with opacity modifiers */
.card {
@apply bg-blue-500/10; /* Worked in v3 inline, not in @apply */
}
/* After: Native CSS works everywhere in v4 */
.card {
@apply bg-blue-500/10; /* Works in v4! */
}
Breaking Changes to Watch
Key Breaking Changes:
- @tailwind → @import "tailwindcss"
- tailwind.config.js → @theme in CSS
- Some renamed utilities:
- decoration-clone → box-decoration-clone
- decoration-slice → box-decoration-slice
- flex-grow → grow (also flex-shrink → shrink)
- Default border color changed from gray-200 to currentColor
- Ring width default changed from 3px to 1px
- Content configuration removed (automatic detection)
When NOT to Upgrade Yet
Wait on upgrading if: you heavily rely on plugins that haven’t added v4 support, your project uses complex tailwind.config.js with JavaScript logic (functions, conditionals), or your team is mid-sprint on a critical release. Consequently, schedule the migration as a dedicated effort rather than mixing it with feature work.
Key Takeaways
Tailwind CSS 4 is faster, simpler, and more capable than v3. The Oxide engine, CSS-first configuration, and automatic content detection eliminate common pain points. As a result, new projects should start with v4, and existing projects should plan migration — the performance gains and simplified setup are worth the effort.