Why Tailwind v4 Is the Biggest Release Ever
Tailwind CSS v4 is not just an incremental update. It is a ground-up rewrite that fundamentally changes how you configure, build, and think about your utility-first CSS framework. The team at Tailwind Labs spent over two years rearchitecting everything from the engine to the configuration system, and the result is something that feels like a completely different tool while maintaining the utility-first philosophy we all love.
The single biggest change? Configuration has moved from JavaScript to CSS. That tailwind.config.js file you have been maintaining for years? It is no longer needed. Instead, you define your design tokens, custom utilities, and theme extensions directly in your CSS using new at-rules like @theme, @variant, and @utility. This might sound like a small change, but it has massive implications for how you structure projects, share configurations, and integrate with other tools.
Under the hood, Tailwind v4 has replaced its PostCSS-based engine with a brand new compiler built on Lightning CSS, a Rust-based CSS parser that is orders of magnitude faster. Build times that used to take seconds now complete in milliseconds. Hot module replacement is nearly instant. The developer experience improvement alone makes the migration worthwhile, but there is so much more to explore.
For the ecosystem, this release means tighter integration with native CSS features. CSS cascade layers, container queries, and modern color spaces are all first-class citizens now. Tailwind v4 does not fight the platform anymore. It embraces it. And that means your CSS output is smaller, more predictable, and easier to debug in browser DevTools.
In this guide, I will walk you through every aspect of migrating from Tailwind v3 to v4, cover all the game-changing new features, and share practical tips from migrating several production applications. Whether you are running a small side project or a large enterprise codebase, this guide has you covered.
Tailwind v4 Migration Overview:
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Tailwind v3 │────▶│ Run Upgrade │────▶│ Tailwind v4 │
│ Project │ │ Tool │ │ Project │
│ │ │ │ │ │
│ tailwind.config │ │ npx @tailwindcss │ │ CSS @theme │
│ postcss.config │ │ /upgrade │ │ No JS config │
│ JS-based config │ │ │ │ Lightning CSS │
└──────────────────┘ └────────┬─────────┘ └──────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Convert Config │ │ Update Imports │ │ Fix Breaking │
│ │ │ │ │ Changes │
│ JS → CSS @theme │ │ @tailwind base │ │ Renamed utils │
│ Custom plugins │ │ → @import │ │ Changed defaults │
│ Theme values │ │ "tailwindcss" │ │ Plugin compat │
└──────────────────┘ └──────────────────┘ └──────────────────┘
│ │ │
└───────────────────┼───────────────────┘
▼
┌──────────────────┐
│ Verify & Test │
│ │
│ Visual regression│
│ Build output │
│ Production ready │
└──────────────────┘What Changed in Tailwind CSS v4
Before diving into the migration steps, let's understand the core architectural changes that make v4 fundamentally different from v3. These are not surface-level tweaks. They represent a philosophical shift in how Tailwind approaches CSS generation and configuration.
CSS-First Configuration with @theme
The most visible change in Tailwind v4 is the move from JavaScript-based configuration to CSS-based configuration. In v3, you defined your theme, plugins, and content paths in a tailwind.config.js or tailwind.config.ts file. In v4, all of that lives directly in your CSS using the new @theme directive. This is not just a syntactic change. It fundamentally changes how Tailwind discovers and processes your design tokens.
With CSS-first configuration, your design tokens are actual CSS custom properties. They show up in browser DevTools. They can be consumed by non-Tailwind code. They participate in the CSS cascade naturally. There is no build step to translate JavaScript objects into CSS. Your tokens are CSS from the start.
Removal of tailwind.config.js
In Tailwind v4, the JavaScript configuration file is gone by default. You do not need tailwind.config.js, tailwind.config.ts, or tailwind.config.cjs anymore. Everything that used to live in those files now has a CSS equivalent. If you are migrating a large project and cannot convert everything at once, Tailwind v4 does provide a compatibility layer via the @config directive that lets you reference a legacy config file. But the goal should be to fully migrate to CSS-first configuration.
Content detection is also automatic now. Tailwind v4 uses smart heuristics to find your template files without needing an explicit content array. It scans your project for files that might contain utility classes and processes them automatically. If you need to explicitly include or exclude paths, you can use the @source directive in your CSS.
Lightning CSS Engine
Tailwind v4 is built on top of Lightning CSS, a Rust-based CSS parser and transformer created by Devon Govett. This replaces the previous PostCSS-based architecture entirely. Lightning CSS handles CSS parsing, vendor prefixing, syntax lowering, and minification all in a single pass. The result is dramatically faster build times and a much simpler toolchain.
You no longer need autoprefixer in your PostCSS config because Lightning CSS handles vendor prefixing natively. You no longer need a separate minifier because Lightning CSS handles that too. The entire build pipeline is consolidated into one high-performance tool. For most projects, you can delete your postcss.config.js file entirely and just use the Tailwind CLI or Vite plugin directly.
Native CSS Cascade Layers
Tailwind v4 uses native CSS @layer rules to organize its output. The framework generates three layers: @layer theme, @layer base, and @layer utilities. This means specificity conflicts between base styles and utility classes are resolved by the browser's native cascade layer system rather than by carefully ordering CSS output. Utilities always win over base styles because the utilities layer has higher priority.
This is a huge improvement for predictability. In v3, you sometimes ran into situations where a base style would unexpectedly override a utility class because of CSS source order or specificity. With native cascade layers, that entire class of bugs disappears. The browser guarantees that utilities always take precedence, regardless of source order.
New Color System with OKLCH
Tailwind v4 has updated its default color palette to use the OKLCH color space. OKLCH provides perceptually uniform colors, meaning that changing the lightness value by the same amount produces visually consistent results across different hues. The default palette still maps to familiar names like blue-500 and red-600, but the underlying values are now in OKLCH for better color interpolation and contrast.
You can still use hex, RGB, or HSL values in your custom theme. Tailwind will handle them correctly. But if you want to take advantage of the new color features like wide-gamut colors and perceptually uniform palettes, OKLCH is the way to go. The browser support for OKLCH is excellent in 2026, covering all modern browsers.
v3 Architecture vs v4 Architecture:
┌─────────────────────────────────────────────────────────────────┐
│ TAILWIND CSS v3 │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ tailwind │──▶│ PostCSS │──▶│ autoprefixer │ │
│ │ .config.js │ │ Plugin │ │ + cssnano │ │
│ │ (JS config) │ │ (Node.js) │ │ (separate tools) │ │
│ └─────────────┘ └──────────────┘ └──────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ content[] │ │ JIT │ │ CSS Output │ │
│ │ paths │ │ Compiler │ │ (multiple passes) │ │
│ └─────────────┘ └──────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
vs.
┌─────────────────────────────────────────────────────────────────┐
│ TAILWIND CSS v4 │
│ │
│ ┌─────────────┐ ┌──────────────────────────────────────────┐ │
│ │ app.css │──▶│ Tailwind v4 Engine (Lightning CSS) │ │
│ │ (@theme, │ │ │ │
│ │ @import) │ │ • CSS parsing (Rust, single pass) │ │
│ │ (CSS only) │ │ • Prefixing (built-in) │ │
│ └─────────────┘ │ • Minification (built-in) │ │
│ │ │ • Syntax lowering (built-in) │ │
│ ▼ │ • Auto content detection │ │
│ ┌─────────────┐ └──────────────────────────────────────────┘ │
│ │ Auto source │ │ │
│ │ detection │ ▼ │
│ │ (no config) │ ┌──────────────────────────────────────────┐ │
│ └─────────────┘ │ Optimized CSS Output (single pass) │ │
│ └──────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘Step-by-Step Migration Guide
Now that you understand what changed and why, let's walk through the actual migration process. I recommend doing this on a dedicated branch so you can compare the before and after and catch any visual regressions. The Tailwind team has also provided an automated upgrade tool that handles most of the heavy lifting, but understanding each step will help you debug issues if they come up.
Step 1: Update Dependencies
The first step is to update your packages. Tailwind v4 has a completely different package structure. The main tailwindcss package is all you need for the core framework, but you will also want the appropriate integration package for your build tool. If you are using Vite, install @tailwindcss/vite. If you are using PostCSS, install @tailwindcss/postcss. If you prefer the CLI, install @tailwindcss/cli.
The npx @tailwindcss/upgrade command is incredibly helpful. It scans your project and automatically converts your tailwind.config.js to CSS @theme syntax, updates your import statements, renames deprecated utilities, and flags any manual changes you need to make. I highly recommend running it as your first step and then reviewing the changes it makes.
Step 2: Update Your Build Tool Configuration
Depending on your build tool, you need to update your configuration to use the new Tailwind v4 integration. The setup is simpler than v3 because you no longer need PostCSS configuration in most cases.
Step 3: Convert tailwind.config.js to CSS @theme
This is the most involved step if you have a heavily customized Tailwind configuration. You need to translate your JavaScript theme object into CSS @theme syntax. The mapping is straightforward but requires attention to naming conventions. In v4, theme values follow a specific naming pattern: --color-* for colors, --font-* for font families, --spacing-* for spacing, and so on.
Step 4: Update CSS Imports
In Tailwind v3, you used the @tailwind directives to inject base styles, components, and utilities. In v4, you simply import Tailwind as a single CSS import. The framework handles layering internally using native CSS cascade layers.
Step 5: Handle Breaking Changes and Renamed Utilities
Tailwind v4 has renamed and removed several utilities. The upgrade tool catches most of these, but you should be aware of the major changes. Some of these are straightforward renames while others reflect deeper changes in how Tailwind handles certain CSS properties.
bg-opacity-*is removed. Usebg-black/50opacity modifier syntax instead.text-opacity-*is removed. Usetext-black/50opacity modifier syntax instead.border-opacity-*is removed. Useborder-black/50opacity modifier syntax instead.flex-shrinkis nowshrinkandflex-growis nowgrow.overflow-ellipsisis nowtext-ellipsis.decoration-sliceanddecoration-cloneare nowbox-decoration-sliceandbox-decoration-clone.- The
ringutility now defaults to 1px instead of 3px. If you relied onringalone, switch toring-3. - Shadow, blur, and other utilities no longer accept bare values.
shadowbecomesshadow-smor a specific size. - The
containerutility is no longer included by default. Use the@utilitydirective to define it if needed.
Step 6: Migrate Plugins
If you were using official Tailwind plugins, many of them have been absorbed into the core framework in v4. The @tailwindcss/container-queries plugin is no longer needed because container queries are built-in. The @tailwindcss/typography plugin has been updated for v4 compatibility. The @tailwindcss/forms plugin continues to work but should be updated to the latest version.
For custom plugins written with the v3 plugin API, Tailwind v4 provides a compatibility path. You can load a legacy config file using the @config directive, which will apply your plugins. However, many simple plugins can be rewritten using the new @utility and @variant CSS directives, which are easier to maintain and do not require JavaScript at all.
New Features Deep Dive
Beyond the migration changes, Tailwind v4 introduces several powerful new features that open up possibilities that were previously difficult or impossible. Let's explore each one in detail.
The @theme Directive
The @theme directive is the heart of Tailwind v4's configuration system. It replaces the theme object in your JavaScript config and generates both CSS custom properties and the corresponding utility classes. When you define --color-brand: #3b82f6 inside @theme, Tailwind automatically creates bg-brand, text-brand, border-brand, and every other color utility for that value.
One of the most powerful aspects of @theme is that it supports namespacing. You can use @theme inline to generate the utility classes without creating CSS custom properties, which is useful for internal values you do not want to expose. You can also use @theme reference to reference existing CSS custom properties without redefining them.
Container Queries Built-In
Container queries are now a first-class feature in Tailwind v4. You no longer need the @tailwindcss/container-queries plugin. The syntax is clean and intuitive. Use @container to define a containment context and then use @sm:, @md:, @lg:, and other container query variants to apply styles based on the container's size rather than the viewport.
This is a game changer for component-based design. Instead of responsive breakpoints that depend on the browser window, your components can adapt to the space they are actually given. A card component in a sidebar can look different from the same card component in a main content area, without any JavaScript or manual class toggling. The component itself is truly responsive and self-contained.
3D Transforms
Tailwind v4 adds built-in support for 3D CSS transforms. You can now use utilities like rotate-x-*, rotate-y-*, rotate-z-*, perspective-*, translate-z-*, and transform-3d to create three-dimensional effects without writing custom CSS. This opens up possibilities for card flip animations, 3D carousels, parallax effects, and immersive UI interactions that previously required manual CSS or animation libraries.
The perspective-* utilities control the depth of the 3D space. Lower values create more dramatic perspective effects while higher values create subtler ones. Combined with transform-style: preserve-3d via the transform-3d utility, you can build complex 3D scenes using nothing but Tailwind classes.
New Gradient Syntax
Gradients in Tailwind v4 are more powerful and flexible. The new gradient utilities support interpolation in different color spaces including OKLCH, which produces perceptually smoother gradients. You can use bg-linear-* for linear gradients (replacing the old bg-gradient-to-* syntax), and there are new bg-radial-* and bg-conic-* utilities for radial and conic gradients. Gradient color stops now support explicit positions using utilities like from-red-500 from-20%.
field-sizing: content
The new field-sizing-content utility is deceptively simple but incredibly useful. It applies field-sizing: content to form elements, which makes textareas and input fields automatically resize based on their content. No more JavaScript auto-resize libraries. No more fixed-height textareas that are either too small or too large. The browser handles the resizing natively, and it works smoothly with animations and transitions.
This is particularly useful for chat interfaces, comment forms, and anywhere you want a textarea that starts small and grows as the user types. Combined with min-h-* and max-h-* utilities, you have full control over the resize behavior without a single line of JavaScript.
Not-* Variants and Inert Support
Tailwind v4 introduces not-* variants that let you apply styles when a condition is NOT met. For example, not-hover:opacity-50 applies reduced opacity when the element is not being hovered. You can combine this with any existing variant: not-focus:border-gray-300, not-disabled:cursor-pointer, and so on.
There is also native support for the inert HTML attribute via the inert:* variant. The inert attribute tells the browser that an element and all its children are non-interactive, which is useful for modal backdrops, disabled form sections, and step-by-step wizards. Combined with inert:opacity-50 inert:pointer-events-none, you can visually indicate non-interactive sections with pure utility classes.
Tailwind v4 Build Pipeline:
┌─────────────────────────────────────────────────────────┐
│ Source Files │
│ .tsx, .jsx, .html, .vue, .svelte, .astro, .blade.php │
└──────────────────────────┬──────────────────────────────┘
│
┌──────▼──────┐
│ Auto Source │
│ Detection │
│ (glob-free) │
└──────┬──────┘
│
┌────────────▼────────────┐
│ app.css Entry │
│ │
│ @import "tailwindcss" │
│ @theme { ... } │
│ @source (optional) │
│ @utility (optional) │
│ @variant (optional) │
└────────────┬────────────┘
│
┌────────────▼────────────┐
│ Lightning CSS Engine │
│ (Rust-based, single │
│ pass processing) │
│ │
│ ┌───────────────────┐ │
│ │ Parse CSS │ │
│ │ Resolve @theme │ │
│ │ Generate utils │ │
│ │ Apply @layer │ │
│ │ Vendor prefix │ │
│ │ Syntax lowering │ │
│ │ Minification │ │
│ └───────────────────┘ │
└────────────┬────────────┘
│
┌────────────▼────────────┐
│ Optimized CSS Output │
│ │
│ @layer theme { ... } │
│ @layer base { ... } │
│ @layer utilities { ... }│
└─────────────────────────┘shadcn/ui Compatibility with Tailwind v4
If you are using shadcn/ui (and if you are reading this blog, there is a good chance you are), migrating to Tailwind v4 requires some specific changes. The shadcn team has been proactive about supporting v4, and the latest version of the CLI generates v4-compatible components out of the box. But if you are migrating an existing project, there are several things you need to update.
The biggest change is in globals.css. In v3, shadcn used HSL values without the hsl() wrapper (like 222.2 84% 4.9%) so that Tailwind's opacity modifiers would work. In v4, opacity modifiers work with any color format, so shadcn has moved to standard OKLCH or HSL values with the function wrapper. The CSS variable names have also changed to follow Tailwind v4's naming conventions.
You will also need to update the cn() utility to ensure tailwind-merge is compatible with Tailwind v4's class names. Install the latest version of tailwind-merge (v3 or later) which has built-in support for Tailwind v4's new utility names and class patterns. The shadcn CLI handles this automatically for new installations, but for existing projects you should run npm update tailwind-merge.
Performance Comparison: v3 vs v4
One of the most compelling reasons to migrate to Tailwind v4 is the massive performance improvement. The Lightning CSS engine is not just a little faster. It is dramatically faster across every metric. Initial build times, incremental rebuilds, and CSS output size all see significant improvements. Here is what the numbers look like for a medium-sized production application with about 500 components and 2000 template files.
Performance Comparison: Tailwind v3 vs v4 ┌────────────────────────────────────────────────────────────┐ │ Build Time (Full) │ │ │ │ v3 ████████████████████████████████████████ 2,100ms │ │ v4 ██████ 285ms │ │ │ │ Improvement: ~7.4x faster │ ├────────────────────────────────────────────────────────────┤ │ Incremental Rebuild (HMR) │ │ │ │ v3 ████████████████████ 180ms │ │ v4 ██ 8ms │ │ │ │ Improvement: ~22x faster │ ├────────────────────────────────────────────────────────────┤ │ CSS Output Size │ │ │ │ v3 ████████████████████████████████ 284kb │ │ v4 ████████████████████████ 198kb │ │ │ │ Improvement: ~30% smaller │ ├────────────────────────────────────────────────────────────┤ │ Dependencies Required │ │ │ │ v3 tailwindcss + postcss + autoprefixer + cssnano (4) │ │ v4 tailwindcss + @tailwindcss/vite (2) │ │ │ │ Improvement: 50% fewer dependencies │ └────────────────────────────────────────────────────────────┘
The incremental rebuild time is the metric that matters most for daily development. Going from 180 milliseconds to 8 milliseconds means your styles update essentially instantly when you save a file. There is no perceptible delay between editing a class and seeing the change in your browser. For teams working on large applications where v3 rebuilds could sometimes spike to 500 milliseconds or more, the improvement is even more dramatic.
The CSS output size reduction comes from several optimizations. Lightning CSS produces more efficient output with fewer redundant rules. Native cascade layers eliminate the need for specificity hacks. And the new engine is better at deduplicating utility definitions. For sites where CSS payload size impacts Core Web Vitals, this is a meaningful improvement that directly affects user experience and SEO.
Common Migration Pitfalls and Solutions
After migrating several production apps to Tailwind v4, I have encountered a number of common issues that trip people up. Here are the most frequent problems and how to solve them quickly.
Pitfall 1: CSS Variable Name Conflicts
Because Tailwind v4 generates CSS custom properties from your @theme values, you can run into conflicts if you already have CSS variables with the same naming pattern. For example, if you had a custom --color-primary variable defined outside of @theme, it will conflict with the one Tailwind generates. The solution is to move all your design token variables inside @theme and remove the duplicate definitions. If you need variables that Tailwind should not generate utilities for, define them outside of @theme using regular CSS custom properties.
Pitfall 2: PostCSS Plugin Order Issues
If you are using the PostCSS integration, make sure @tailwindcss/postcss is the only CSS processing plugin you need. Remove autoprefixer from your PostCSS config because Tailwind v4 handles prefixing internally. Having autoprefixer alongside @tailwindcss/postcss can cause duplicate prefixes and unexpected CSS output. Also remove any separate minification plugins like cssnano since Lightning CSS handles minification in production builds automatically.
Pitfall 3: The ring Utility Default Change
This one catches almost everyone. In v3, the ring utility applied a 3px ring by default. In v4, ring applies a 1px ring. If you have focus styles like focus:ring focus:ring-blue-500, your focus rings will look much thinner after migration. The fix is simple: change ring to ring-3 everywhere you want the old default width. The upgrade tool should catch most of these, but it might miss some in dynamic or computed class strings.
Pitfall 4: Third-Party Plugin Incompatibility
Not all third-party Tailwind plugins have been updated for v4. If you depend on community plugins, check their repositories for v4 compatibility before migrating. For plugins that have not been updated, you can use the @config directive to load a compatibility config, but this should be a temporary measure. Many simple plugins can be replaced with @utility and @variant directives in your CSS. For complex plugins, consider opening an issue on the plugin's repository to request v4 support.
Pitfall 5: Dynamic Class Generation
If your project generates Tailwind classes dynamically using string concatenation or template literals, Tailwind v4's source detection might not pick them up. This was also a problem in v3, but v4's automatic content detection makes it more likely to surface. The solution is the same: never dynamically construct class names. Use complete class strings and let Tailwind's scanner find them. If you must use dynamic classes, use the @source directive to explicitly include the files where they are defined, or use a safelist approach with @utility.
Pitfall 6: Dark Mode Configuration Changes
In Tailwind v3, you configured dark mode strategy in tailwind.config.js using darkMode: 'class' or darkMode: 'media'. In v4, dark mode uses the prefers-color-scheme media query by default. If your project uses class-based dark mode (which is common with next-themes or similar libraries), you need to explicitly configure this in your CSS. Without this change, your dark mode toggle will stop working.
Advanced Tips for a Smooth Migration
Beyond avoiding pitfalls, here are some advanced strategies that will make your migration smoother and help you take full advantage of v4's new capabilities.
First, consider migrating incrementally if you have a large codebase. Use the @config directive to keep your existing JavaScript configuration working while you gradually convert sections to CSS @theme syntax. This lets you ship the migration in multiple pull requests instead of one massive changeset. You can remove the @config reference once everything has been converted.
Second, set up visual regression testing before you start. Tools like Chromatic, Percy, or even simple screenshot comparisons can catch subtle visual differences that are easy to miss in manual testing. Tailwind v4's default values differ from v3 in some cases (like the ring width change), and these differences can compound across a large application.
Third, take the opportunity to clean up your design tokens during migration. Converting from JavaScript to CSS is a natural point to audit your theme values, remove unused tokens, and consolidate similar values. Many projects accumulate theme cruft over time, and a migration is the perfect excuse to trim it down.
Fourth, update your editor tooling. The Tailwind CSS IntelliSense VS Code extension needs to be updated to support v4 syntax. The latest version understands @theme, @utility, and @variant directives and provides autocomplete for the new class names. Without the update, you will get false error highlighting in your CSS files and miss out on autocomplete for new features.
Real-World Migration Example
To make this guide more concrete, let me walk through a condensed example of migrating a real Next.js application from Tailwind v3 to v4. This application uses shadcn/ui, next-themes for dark mode, and has a custom design system with branded colors and typography.
Notice how much cleaner the v4 version is. The configuration is co-located with your styles, there is no JavaScript to parse, and the intent is immediately clear. The @plugin directive replaces the plugins array for loading JavaScript plugins that have been updated for v4. The @variant dark line replaces the darkMode: "class" config option. And automatic content detection means you do not need to specify content paths at all.
Migration Checklist
Before you consider your migration complete, run through this checklist to make sure everything is properly converted and working. I use this exact checklist when migrating production applications and it has saved me from shipping broken styles more than once.
- Run
npx @tailwindcss/upgradeand review all automated changes before committing. - Update
tailwindcssto v4 and install the appropriate integration package (@tailwindcss/viteor@tailwindcss/postcss). - Remove
autoprefixerandcssnanofrom your dependencies and PostCSS config. - Convert
tailwind.config.jsto CSS@themein your main stylesheet. Delete the JS config file when done. - Replace
@tailwind base; @tailwind components; @tailwind utilities;with@import "tailwindcss"; - If using class-based dark mode, add
@variant dark (&:where(.dark, .dark *));to your CSS. - Update
ringtoring-3wherever you relied on the old 3px default. - Replace deprecated opacity utilities (
bg-opacity-*,text-opacity-*) with opacity modifier syntax (bg-black/50). - Remove
@tailwindcss/container-queriesplugin if installed. Container queries are now built-in. - Update
tailwind-mergeto v3+ for compatibility with v4 class names. - Update the Tailwind CSS IntelliSense VS Code extension to the latest version.
- Test all pages visually, paying special attention to focus rings, shadows, gradients, and dark mode.
- Run your test suite and check for any CSS-related assertion failures.
- Verify build output size and build times to confirm performance improvements.
- Remove any legacy
@configreferences once all plugins have been migrated.
Conclusion
Tailwind CSS v4 is the most significant release in the framework's history. The move to CSS-first configuration, the Lightning CSS engine, and the embrace of native CSS features like cascade layers and container queries represent a maturation of the utility-first approach. Tailwind is no longer fighting the platform. It is building on top of it, and the result is a faster, simpler, and more powerful framework.
The migration process is straightforward for most projects, especially with the automated upgrade tool handling the bulk of the changes. The key is to understand what changed and why, so you can make informed decisions when the tool cannot automatically convert something. The step-by-step guide and pitfall list in this article should give you everything you need to migrate confidently.
If you are starting a new project in 2026, there is no reason to use Tailwind v3. Go straight to v4 and enjoy the faster builds, cleaner configuration, and powerful new features. If you are maintaining an existing v3 project, start planning your migration now. The performance benefits alone justify the effort, and the improved developer experience will pay dividends every day your team works on the codebase.
The future of CSS is exciting, and Tailwind v4 is leading the charge. Container queries, 3D transforms, OKLCH colors, native cascade layers, and CSS-first configuration are not just buzzwords. They are practical tools that make building modern web interfaces faster and more enjoyable. Start your migration today and experience the difference for yourself.