Tailwind CSS v4 Complete Migration & Architectural Guide: CSS-First Engine, Themes & JIT
Everything you need to know about migrating to Tailwind CSS v4. Learn how the new Rust-powered Oxide engine, CSS-first `@theme` directives, and zero-config setup slash build times by 10x.
1. Why Tailwind CSS v4 is a Ground-Up Rewrite
For years, Tailwind CSS relied on a JavaScript-based architecture: a `tailwind.config.js` file defining color palettes, spacing tokens, and plugins, parsed through PostCSS pipelines. While effective, large enterprise codebases suffered from slow initial builds, complex JS-to-CSS serialization, and heavy node_modules footprints.
Tailwind CSS v4 completely reimagines the framework as a CSS-first, high-performance engine powered by the lightning-fast Rust-based 'Oxide' compiler. There is no `tailwind.config.js`, no PostCSS requirement, and no complex configuration file.
Instead, your design system is configured directly in standard CSS using native `@theme` directives, unlocking instantaneous HMR and up to 10x faster production builds.
2. The CSS-First `@theme` Directive Explained
In Tailwind v4, defining custom colors, fonts, and border radii happens directly inside your global CSS file using the `@theme` block. This eliminates the disconnect between CSS custom properties and Tailwind utility classes.
Every variable defined inside `@theme` automatically registers corresponding utility classes (e.g. defining `--color-brand-primary` generates `bg-brand-primary`, `text-brand-primary`, `border-brand-primary`, etc.):
@import "tailwindcss";
@theme {
--color-signal: #00f2fe;
--color-signal-hover: #4facfe;
--color-surface-1: #0b0f19;
--color-surface-2: #111827;
--color-surface-3: #1f293d;
--font-display: "Cabinet Grotesk", sans-serif;
--font-body: "Inter", sans-serif;
--radius-custom: 1.25rem;
--shadow-lift: 0 20px 40px -15px rgba(0, 242, 254, 0.15);
}
/* Custom dark mode and fluid responsive design */
:root {
color-scheme: dark;
--bg-canvas: #06090e;
--text-primary: #f8fafc;
}
body {
background-color: var(--bg-canvas);
color: var(--text-primary);
font-family: var(--font-body);
}3. Automatic Content Detection (No More `content` Globs!)
One of the most frequent bugs in Tailwind v3 occurred when developers created new directories (e.g. `src/modules/billing/`) and forgot to update the `content: ['./src/**/*.{js,ts,jsx,tsx}']` array in `tailwind.config.js`. Classes simply failed to generate.
In Tailwind v4, content detection is fully automated. The Oxide compiler scans your project tree using high-speed gitignore-aware filesystem watchers. It indexes all relevant source files automatically, generating only the utilities you actually use without manual configuration.
If you have external assets or monorepo packages that need explicit indexing, you can simply use the `@source` directive in your CSS:
@import "tailwindcss";
/* Scan an external workspace package in a monorepo */
@source "../packages/ui/src";
@source "../packages/templates/**/*.tsx";4. Modern CSS Features Built-In: Cascading Layers & CSS Nesting
Tailwind v4 takes full advantage of modern browser capabilities:
1. Native CSS `@layer`: Utilities are emitted in standard browser `@layer` boundaries (theme, base, components, utilities), preventing specificity wars and eliminating the need for aggressive `!important` overrides.
2. Native CSS Nesting: Write clean, standard nested rules directly without third-party preprocessor plugins.
3. Dynamic Arbitrary Values: Support for modern color spaces like `oklch()`, dynamic viewport units (`100dvh`), and CSS container queries (`@container`) is fully native.
5. Migration Checklist: Moving from v3 to v4
Follow these essential steps when upgrading your production projects to Tailwind v4:
1. Replace `npm install tailwindcss postcss autoprefixer` with `@tailwindcss/vite` in your Vite configuration.
2. Delete `tailwind.config.js` and `postcss.config.js`.
3. Replace `@tailwind base; @tailwind components; @tailwind utilities;` with `@import "tailwindcss";`.
4. Move custom theme extensions into `@theme { ... }` in your primary stylesheet.
5. Run your test suite and verify build times—expect a 5x to 10x speed improvement.
Is PostCSS still required with Tailwind CSS v4?
No. If you use modern bundlers like Vite, Tailwind v4 runs as a native bundler plugin, completely bypassing PostCSS for maximum speed.
Can I still use arbitrary values like w-[320px] in v4?
Yes, arbitrary values and variant modifiers (like hover, focus-visible, and data-* attributes) remain fully supported and compile faster than ever.
How does Tailwind v4 handle dark mode?
Tailwind v4 supports both native CSS media queries (`prefers-color-scheme`) and class-based dark mode (`.dark`), seamlessly controlled via CSS custom properties.