Tailwind CSS v4: What Changed, Why It Matters, and How to Migrate Your Project

Tailwind CSS v4 is a ground-up rewrite that changes how you configure the framework, how it generates CSS, and how you extend it. If you have a project on v3, upgrading is not a minor version bump. But the new architecture is genuinely better: faster builds, smaller output, and a CSS-native configuration model that removes a significant layer of tooling complexity.

The Biggest Change: CSS-First Configuration

In Tailwind v3, you configured the framework in a JavaScript file (tailwind.config.js). In v4, configuration lives in your CSS file using CSS custom properties and @theme directives. Your design tokens become CSS variables, not JavaScript objects.

This is a significant philosophical shift. Your theme is now part of your CSS layer rather than a build-time JavaScript configuration. This means design tokens are available at runtime (you can read them with JavaScript, use them in inline styles, and access them from anywhere CSS is available) rather than existing only at build time.

The @theme directive in your CSS file replaces the theme key in tailwind.config.js. Instead of:

// tailwind.config.js
module.exports = {
  theme: {
    colors: {
      brand: '#a855f7'
    }
  }
}

You write:

/* styles.css */
@import "tailwindcss";
@theme {
  --color-brand: #a855f7;
}

The New Engine: Lightning CSS

Tailwind v4 uses Lightning CSS as its processing engine instead of PostCSS. This change delivers dramatically faster build times: projects that took seconds to compile with v3 compile in milliseconds with v4. For large projects with extensive utility usage, this improvement is significant and immediately noticeable in development feedback loops.

The Lightning CSS switch also means PostCSS is no longer a dependency for most Tailwind setups. If you were using PostCSS primarily for Tailwind, you can simplify your build configuration significantly.

What Got Removed

v4 removes several v3 features that require attention during migration:

• @tailwind base/components/utilities directives: Replaced by a single @import "tailwindcss".
• The safelist config option: Use explicit CSS or component-level styles instead.
• JavaScript theme functions in config: These no longer exist since config is CSS-native.
• Some deprecated utilities: Several v2-era utilities that were kept for compatibility in v3 are removed in v4.

New Features Worth Knowing

Container Queries (Native Support)

v4 includes native support for CSS container queries without a plugin. The @container variants work out of the box, letting you build components that respond to their container's size rather than the viewport size. This is the right model for component-level responsive design.

3D Transform Utilities

New utilities for 3D transforms (rotate-x-*, rotate-y-*, perspective-*) are included by default, making 3D UI elements much simpler to implement without custom CSS.

Cascade Layers

Tailwind v4 uses CSS cascade layers for all generated styles, which means Tailwind utilities no longer conflict with other CSS you write. The specificity battle that occasionally required ! important modifiers is largely eliminated.

Migration Strategy

The Tailwind team provides an official migration guide and a codemod tool (npx @tailwindcss/upgrade) that handles the most common automated migrations. Run the codemod first, then address what it cannot automate.

For most projects, the migration involves: running the codemod, converting JavaScript theme configuration to CSS @theme blocks, removing the PostCSS setup if it was only for Tailwind, updating any custom plugins to the v4 plugin API, and testing the output visually across your main page templates.

Plan 4 to 8 hours for a typical mid-size project. Larger projects with extensive customization or complex plugin usage will take longer. The result is a leaner build setup and significantly faster development compilation.

Our projects at Innovativus are migrating to Tailwind v4 progressively, starting with new projects. If you need help with a migration or want to discuss frontend architecture, reach out.