Migrating to Tailwind CSS v4: what actually changed
A practical guide to the breaking changes in Tailwind v4 and what you need to update in your project.
Tailwind v4 is a ground-up rewrite. If you've been using v3, the mental model mostly carries over, but the configuration layer is completely different.
The big changes
No more tailwind.config.js. All configuration now lives in CSS, inside an @theme block in your main stylesheet. Custom colors, spacing, fonts — all defined as CSS custom properties.
PostCSS plugin changed. You now import @tailwindcss/postcss instead of tailwindcss. Your postcss.config.mjs needs to be updated.
Arbitrary values still work, but the CSS variable syntax for opacity modifiers changed slightly.
What to update
- Replace your
tailwind.config.jstheme extensions with@themeblocks in CSS - Update your PostCSS config to use the new plugin
- Replace
next lintwitheslintin your package.json scripts — Next.js 16 dropped the built-in lint command
What didn't change
The utility class names are almost entirely the same. Your existing markup will work. The migration cost is mostly in the config layer, not the templates.
Worth it?
Yes. The DX is better — faster builds, no config file to maintain, and CSS variables give you runtime theming for free.