Tailwind CSS v4 Migration Guide: What Changed and What Breaks

Tailwind CSS v4 shipped with a new engine, new class names, and some breaking changes. Here's what you need to know to migrate smoothly.

What's New in v4

New engine — Built on Oxide, significantly faster builds
CSS-first configuration — Configure in CSS instead of JavaScript
New class names — Some utilities were renamed for consistency
Browser build — @tailwindcss/browser replaces the CDN script

Breaking Changes

v3	v4
`bg-gradient-to-r`	`bg-linear-to-r`
`bg-opacity-50`	`bg-black/50` (color opacity)
`backdrop-blur-sm`	`backdrop-blur-xs`
`tailwind.config.js`	CSS-based config with `@theme`
`cdn.tailwindcss.com`	`@tailwindcss/browser`

Migration Checklist

Update the Tailwind CSS package: npm install tailwindcss@latest
Replace bg-gradient-to-* with bg-linear-to-*
Replace opacity utilities with color opacity syntax (/50)
Move config from tailwind.config.js to CSS @theme block
Update CDN script to @tailwindcss/browser
Test dark mode — the dark: prefix works the same way
Run your build and fix any remaining class name warnings

💡 Pro tip: The Tailwind CSS team provides an automatic migration tool. Run npx @tailwindcss/upgrade to handle most of the class name changes automatically.

The migration is straightforward for most projects. The biggest change is the config format — moving from JavaScript to CSS. The new engine is noticeably faster, especially on large projects.

bg-gradient-to-r

bg-linear-to-r

bg-opacity-50

bg-black/50 (color opacity)

backdrop-blur-sm

backdrop-blur-xs

tailwind.config.js

CSS-based config with @theme

cdn.tailwindcss.com

@tailwindcss/browser

Migration Checklist

Update the Tailwind CSS package: npm install tailwindcss@latest

Replace bg-gradient-to-* with bg-linear-to-*

Replace opacity utilities with color opacity syntax (/50)

Move config from tailwind.config.js to CSS @theme block

Update CDN script to @tailwindcss/browser

Test dark mode — the dark: prefix works the same way

Run your build and fix any remaining class name warnings

💡 Pro tip: The Tailwind CSS team provides an automatic migration tool. Run npx @tailwindcss/upgrade to handle most of the class name changes automatically.

The migration is straightforward for most projects. The biggest change is the config format — moving from JavaScript to CSS. The new engine is noticeably faster, especially on large projects.