Migrating to Tailwind CSS v4: What Changed and Why It Matters
Why v4 Is a Big Deal
Tailwind CSS v4 isn't a incremental update — it's a ground-up rewrite. The team rebuilt the engine, changed the configuration model, updated the plugin ecosystem, and overhauled how design tokens work. The result is faster builds, a cleaner developer experience, and a more CSS-native approach to design systems.
If you're starting a new project in 2026, use v4 from day one. If you have an existing v3 project, this guide walks through what changed and how to migrate.
What's New in Tailwind CSS v4
1. CSS-First Configuration (No More tailwind.config.ts)
The biggest change: your configuration lives in CSS now, not JavaScript. Instead of a `tailwind.config.ts` file, you use the `@theme` directive directly in your stylesheet.
**v3 approach:**
```js
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
primary: "#6366f1",
secondary: "#ec4899",
},
fontFamily: {
sans: ["Inter", "sans-serif"],
},
},
},
};
```
**v4 approach:**
```css
/* globals.css */
@import "tailwindcss";
@theme inline {
--color-primary: #6366f1;
--color-secondary: #ec4899;
--font-sans: "Inter", sans-serif;
}
```
The `@theme inline` block defines CSS custom properties that Tailwind uses to generate utility classes. You get `text-primary`, `bg-secondary`, and so on — same as before, but defined in CSS where design tokens belong.
The `inline` keyword tells Tailwind to output the tokens as-is into the `:root` block, rather than generating a separate set of variables. For most projects, `@theme inline {}` is what you want.
2. New PostCSS Plugin
The PostCSS plugin changed from `tailwindcss` to `@tailwindcss/postcss`. Update your PostCSS config:
**Before:**
```js
// postcss.config.js
module.exports = {
plugins: { tailwindcss: {}, autoprefixer: {} },
};
```
**After:**
```js
// postcss.config.js
module.exports = {
plugins: { "@tailwindcss/postcss": {} },
};
```
Note that `autoprefixer` is no longer needed — Tailwind v4 handles vendor prefixes internally.
3. The Oxide Engine (Much Faster Builds)
Tailwind v4 introduces Oxide, a new Rust-based engine. Build times drop by 5-10x on large projects. Incremental builds (hot reload) are near-instant even in large codebases.
This isn't just a developer experience win — faster builds mean shorter CI pipelines and faster deployments.
4. Updated Color System
The default color palette was updated. If you relied on specific v3 gray shades like `gray-900`, some values have changed. Define your own color tokens in `@theme` for full control and no surprise changes on future updates.
5. Container Queries Built In
Tailwind v4 includes container query utilities without a plugin. Use `@container` on a parent and `@sm:`, `@md:`, etc., on children:
```html
<div class="@container">
<div class="@sm:grid-cols-2 grid grid-cols-1">
<!-- responds to parent width, not viewport width -->
</div>
</div>
```
Container queries are more composable than media queries for component-based design. This was previously only available via the `@tailwindcss/container-queries` plugin.
6. CSS Import Syntax
The old `@tailwind base; @tailwind components; @tailwind utilities;` directives are replaced with a single CSS import:
```css
/* v4 */
@import "tailwindcss";
```
Migration Steps
Here's the practical path from v3 to v4:
Step 1: Update Dependencies
```bash
npm install tailwindcss@latest @tailwindcss/postcss
npm uninstall autoprefixer
```
Step 2: Update PostCSS Config
Replace `tailwindcss` with `@tailwindcss/postcss` and remove `autoprefixer` as shown above.
Step 3: Update Your CSS Entry Point
Replace the three `@tailwind` directives with `@import "tailwindcss"`, then add your `@theme` block with custom tokens.
Step 4: Move Theme Config to CSS
Take everything from `theme.extend` in your config file and convert it to CSS custom properties inside `@theme inline {}`. The naming convention is: `colors.primary` becomes `--color-primary`, `fontFamily.sans` becomes `--font-sans`.
Step 5: Delete tailwind.config.ts
Once your tokens are in CSS, delete the config file. You no longer need it.
Step 6: Check for Breaking Changes
Run your dev server and look for visual regressions. The most common issues are:
- Gray shades that look slightly different (redefine them in `@theme`)
- Custom plugins that need to be updated for v4's API
- JIT-mode edge cases that behaved differently in v3
The official migration guide at tailwindcss.com covers edge cases in detail.
Why It Matters for Your Projects
The CSS-first approach isn't just aesthetic — it has real implications:
**Better IDE support.** CSS variables are natively understood by editors. No more relying on Tailwind IntelliSense for basic autocomplete.
**Simpler onboarding.** New team members don't need to learn the Tailwind config schema. If they know CSS, they can read the token definitions immediately.
**Smaller configuration surface.** Fewer files to maintain. The config file was always a bit awkward — JavaScript that generates CSS. CSS that generates CSS is cleaner.
**Faster iteration.** With Oxide, changes appear in the browser nearly instantly. The feedback loop is tighter.
All Craftly templates are built with Tailwind CSS v4 from the ground up — no legacy config file, `@theme inline {}` for design tokens, and the `@tailwindcss/postcss` plugin. If you want to see what a well-structured v4 project looks like in practice, the [SaaSify template](https://getcraftly.gumroad.com/l/mrcek) is a good reference point.
The Bottom Line
Tailwind v4 is a better tool. The CSS-first configuration is cleaner, the Oxide engine is dramatically faster, and container queries make component design more composable. The migration is real work — especially for large projects — but the result is worth it.
For new projects, there's no reason not to use v4 today. For existing projects, plan the migration as part of your next major dependency update cycle. The sooner you move, the more time you save on every build going forward.