Tailwind CSS v3 → v4 Migration

Tailwind CSS v4 is a ground-up rewrite that changes the fundamental configuration model. In Tailwind v3, all customization lived in a JavaScript tailwind.config.js file — colors, spacing, fonts, breakpoints, dark mode settings, and plugins. In Tailwind CSS v4, configuration moves into CSS itself using the new @theme directive and CSS custom properties. This Tailwind v3 to v4 migration tool automatically converts your tailwind.config.js into the equivalent @theme CSS block, handling colors, spacing, screens, fonts, dark mode, and plugins.

What changed in Tailwind CSS v4: The tailwind.config.js file is no longer required or recommended. Instead, you define your design tokens directly in CSS using @theme { --color-brand: #6366f1; }. Tailwind v4 uses CSS custom properties (CSS variables) as the underlying mechanism, which means your theme values are accessible anywhere in your CSS without extra tooling. The content configuration for template scanning is now inferred automatically using a new file-system detector, eliminating one of the most common Tailwind v3 footguns.

The @theme directive is Tailwind v4's replacement for the theme.extend block in your config. You define CSS variables inside @theme { } using Tailwind's naming conventions: --color-* for colors, --spacing-* for spacing, --font-* for font families, --breakpoint-* for responsive breakpoints. These variables automatically generate utility classes — --color-brand: #6366f1 creates bg-brand, text-brand, border-brand, and all their variants.

Common Tailwind v3 to v4 migration pitfalls: The darkMode: 'class' config becomes a @custom-variant dark (&:where(.dark, .dark *)); declaration in CSS. Tailwind CSS plugins written for v3 may need updates or replacements since the plugin API has changed. The @tailwindcss/forms and @tailwindcss/typography plugins have v4-compatible releases. The theme() CSS function syntax changes slightly. JIT mode is now always on. The @layer utilities and @layer components patterns still work but custom utilities can also be defined with @utility.

Do you need to rewrite all your Tailwind classes? In most cases, no. Tailwind v4 maintains backward compatibility for most utility classes — flex, text-sm, bg-blue-500, p-4, and the vast majority of utilities you use daily still work unchanged. What changes is how you configure custom tokens, not how you use built-in ones. You'll need to update your tailwind.config.js customizations, your build configuration (switching from PostCSS plugin to the new @tailwindcss/vite Vite plugin or the standalone CLI), and any v3-only plugin syntax.

How to use this migration tool: Paste your tailwind.config.js content into the left panel. The tool parses your theme and theme.extend blocks and generates the equivalent @theme { } CSS. Review the migration notes panel — it flags items that couldn't be automatically converted (like custom plugins or complex darkMode configurations) and suggests the manual equivalent. Copy the output, add it to your main CSS file after your @import "tailwindcss" statement, and update your build tool configuration to use the Vite plugin or CLI.