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/browserreplaces 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-*withbg-linear-to-* - Replace opacity utilities with color opacity syntax (
/50) - Move config from
tailwind.config.jsto CSS@themeblock - 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.