Tailwind CSS v4: What Changed and How to Migrate
Everything that changed in Tailwind CSS v4 — the new CSS-first configuration, removed features, and a practical migration checklist for existing projects.
The big shift: CSS-first configuration
The biggest change in Tailwind v4 is that configuration moved from JavaScript (tailwind.config.js) to CSS. You customize your theme using a @theme directive in your CSS file instead of editing a JavaScript object. This is a fundamental architectural change, not just a syntax tweak.
Why does this matter? CSS-first config means faster builds, no config file to maintain, and your customizations live next to your styles instead of in a separate file. For most projects, you don't need any configuration at all — the defaults work.
What was removed
Tailwind v4 dropped some features that were rarely used or replaced by better alternatives. The @apply directive still works but is discouraged. Arbitrary variants with square bracket syntax changed slightly. Some utility naming conventions were updated for consistency.
The plugin system was simplified. Most commonly used plugins like @tailwindcss/typography and @tailwindcss/forms are now built in or available as separate packages with simpler integration.
New features worth knowing
Container queries are now built in with the @container directive. This lets components respond to their container's size instead of the viewport — a huge improvement for reusable components.
The color system was expanded with wider gamut support. New utility classes for oklch and oklab color spaces give you more vibrant, perceptually uniform colors. The zinc, slate, and stone gray scales were refined.
Migration checklist
Step 1: Update packages. Install tailwindcss@4 and @tailwindcss/postcss. Remove the old tailwindcss and postcss-import if you're using it. Step 2: Delete tailwind.config.js (or .ts). Move any theme customizations to a @theme block in your globals.css.
Step 3: Update your CSS entry point. Replace @tailwind base, @tailwind components, @tailwind utilities with a single @import 'tailwindcss'. Step 4: Run your dev server and fix any class name changes — Tailwind will warn you about deprecated utilities.
Common gotchas
The most common migration issue is custom colors. In v3, you defined them in the config file. In v4, you define them in CSS: @theme { --color-brand: #7c3aed; }. Then use them as bg-brand, text-brand, etc.
Another gotcha: if you're using @apply in component CSS, make sure the utilities you're applying still exist in v4. Some class names changed — check the Tailwind v4 docs for the full list of renames.
Should you migrate?
If you're starting a new project, absolutely use v4. It's faster, simpler, and the defaults are better. If you have an existing project that works fine on v3, migration is optional — v3 is still supported and receiving security updates.
For our templates and client projects, everything is built on Tailwind v4. The simpler config story and faster build times make it the clear choice for new work. Need help migrating a project or building something new? We build with Tailwind v4 every day — start a project with us.
Need a custom version?
We build it for you.
Custom web applications, business systems, and marketing sites — built to your exact specifications. Projects starting from $2K.