Tailwind CSS v4: What's New and How to Migrate Your Projects

Tailwind CSS v4 is a significant rethink of the framework — not just an incremental update. It replaces the PostCSS-based build pipeline with a Lightning CSS engine, introduces CSS-first configuration, and removes the JavaScript config file. The result is faster builds, smaller output, and a more intuitive developer experience.

CSS-First Configuration: No More tailwind.config.js

The biggest change in v4 is the elimination of tailwind.config.js. All configuration now lives in your CSS file using @theme, @utility, and @variant directives.

/* app.css — replaces tailwind.config.js completely */
@import "tailwindcss";

@theme {
  --font-family-display: "Inter", sans-serif;
  --color-brand: #6c5ce7;
  --color-brand-dark: #5a4bd1;
  --color-surface: #f8fafc;
  --breakpoint-3xl: 120rem;
}

@utility container-narrow {
  max-width: 48rem;
  margin-inline: auto;
  padding-inline: 1rem;
}

No more splitting configuration between a JavaScript object and your CSS utilities. Every design token lives in the same file where you define your base styles. This eliminates the mental overhead of jumping between config files to understand design decisions.

Lightning CSS Integration

Tailwind CSS v4 ships with Lightning CSS built in — Rust-based processing that replaces PostCSS, autoprefixer, and cssnano. Build speeds improve 10-15x for large projects.

# Before — v3 with multiple PostCSS plugins
npm install tailwindcss postcss autoprefixer cssnano

# After — v4 with integrated Lightning CSS
npm install tailwindcss @tailwindcss/vite

// vite.config.ts — v4 setup is minimal
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()],
})

No postcss.config.js needed. No separate autoprefixer configuration. Lightning CSS handles vendor prefixes, minification, and nested CSS natively. The single-tool approach reduces the number of dependencies in your project.

New Directives and Features

Tailwind CSS v4 introduces several new directives that replace patterns previously handled by custom plugins.

Container Queries Built In

<div class="@container">
  <div class="@lg:grid-cols-3 grid gap-4">
    <div class="p-4">Responds to container width</div>
  </div>
</div>

Container queries are now a first-class feature with the @ prefix — no plugin installation required.

Custom Variants with @variant

@variant not-mobile (@media (width >= 48rem));
@variant dark (&:where(.dark, .dark *));
@variant hover-only (@media (hover: none));

Use these in your HTML directly:

<div class="not-mobile:flex hover-only:touch-action-manipulation">

The @starting-style Support

Animate elements on first render with CSS @starting-style support:

@utility fade-in {
  opacity: 0;
  @starting-style {
    opacity: 1;
  }
}

Migration Strategy from v3

Migrating from v3 requires a systematic approach. Do not attempt it as a single pull request for a large project.

1. Upgrade dependencies: Replace tailwindcss with tailwindcss@next, switch to the new Vite or webpack plugin
2. Migrate config to CSS: Create @theme blocks for every value in your tailwind.config.js — colors, fonts, spacing, breakpoints
3. Update @apply usage: In v4, @apply can only be used in a @layer block
4. Replace custom plugins: Most Tailwind CSS plugins have v4 equivalents or can be replaced with @utility directives

/* Before — v3 config */
/* tailwind.config.js */
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#6c5ce7' },
      fontFamily: { display: ['Inter', 'sans-serif'] },
    },
  },
  plugins: [
    require('@tailwindcss/container-queries'),
    require('@tailwindcss/typography'),
  ],
}

/* After — v4 CSS-first config */
/* app.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@theme { --color-brand: #6c5ce7; }

Performance Improvements in Production Builds

Tailwind CSS v4 generates CSS on demand only for classes it detects in your source files — no more scanning thousands of utility variants that never appear in your markup. Combined with Lightning CSS, production builds produce CSS files that are typically 30-50% smaller than v3 equivalents.

Metric               | v3           | v4
---------------------|--------------|---------------
Build time (100k)    | ~12s         | ~1.5s
CSS output (unused)  | ~12KB        | ~3KB
CSS output (project) | ~85KB        | ~52KB
Dependencies         | 150+         | 20+

Tailwind CSS v4 represents the framework's most ambitious evolution. The CSS-first configuration, Lightning CSS integration, and built-in container queries make it both faster and more intuitive than v3. At SoniNow, we help teams migrate their styling infrastructure smoothly while taking full advantage of v4's performance improvements.

Ready to upgrade your styling setup? Contact SoniNow for a Tailwind CSS v4 migration plan and frontend optimization consultation.