Tailwind CSS 4 Migration Cheatsheet

Tailwind CSS 4 is a major rewrite that changes how you configure and use the framework. The core engine has been rebuilt for performance, the configuration system has shifted from JavaScript to CSS, and several utility classes have been renamed or replaced. If you are migrating an existing Tailwind 3 project, this cheatsheet covers every breaking change, every new feature, and gives you a step-by-step migration path. The biggest conceptual shift is configuration. In Tailwind 3, you had a tailwind.config.js (or .ts) file where you defined your theme, plugins, and content paths. In Tailwind 4, configuration moves into your CSS file using the @theme directive. Your main CSS file becomes the single source of truth: @import "tailwindcss"; @theme { --color-primary: #3b82f6; --color-secondary: #10b981; --font-sans: "Inter", sans-serif; }. Content detection is now automatic. Tailwind 4 uses heuristic-based content detection, scanning your project for template files without needing an explicit content array. This means you can delete the content configuration in most cases. If you need to explicitly include or exclude paths, use the @source directive in your CSS file. Breaking changes in utility classes. The bg-opacity-*, text-opacity-*, and border-opacity-* utilities are removed. Use the modern CSS color syntax instead: bg-blue-500/75 for 75% opacity. The flex-shrink and flex-grow utilities are now shrink and grow (the old names still work as aliases but are deprecated). The overflow-ellipsis utility is now text-ellipsis. The decoration-slice and decoration-clone utilities are now box-decoration-slice and box-decoration-clone. Shadow, radius, and blur scales have been recalibrated. If your design relies on exact shadow or blur values from Tailwind 3, you may need to adjust. The new defaults are more visually consistent but subtly different. Test your UI after migration and tweak using custom theme values if needed. New features worth adopting immediately. Container queries are built-in. Use @container on a parent and then @sm:, @md:, @lg: variants on children to style based on container width instead of viewport width. This is transformative for component-based design systems. The new variant system supports arbitrary grouping. Group multiple variants with a cleaner syntax. Use has-* variants to style parents based on child state. Use not-* variants for negation. The in-* variant lets you style elements based on ancestor state. CSS cascade layers are now used internally, which means Tailwind plays better with third-party CSS. Your utility classes will always override component and base styles as expected, without specificity hacks. Migration steps. Step 1: update your package. Install Tailwind CSS 4 and the new Vite plugin or PostCSS plugin. The package name remains tailwindcss but the PostCSS plugin setup changes. For Vite projects, use @tailwindcss/vite. For PostCSS projects, use @tailwindcss/postcss. Step 2: update your CSS entry point. Replace the three @tailwind directives (base, components, utilities) with a single @import "tailwindcss"; statement. Move your theme customizations from tailwind.config.js into @theme {} blocks in your CSS file. Step 3: migrate plugins. First-party plugins like @tailwindcss/typography and @tailwindcss/forms have been updated for v4. Install the latest versions. For custom plugins that use the JavaScript plugin API, check if they need updates. Many simple plugins can be replaced with @utility and @variant directives in CSS. Step 4: run the automatic migration tool. Tailwind provides a codemod: npx @tailwindcss/upgrade. This handles the most common renames and configuration changes automatically. Review the changes it makes before committing. Step 5: manual cleanup. Search your codebase for deprecated utility patterns (bg-opacity-*, text-opacity-*, etc.) and replace them with the new syntax. Update any dynamic class generation to use the new names. Test every page and component visually. Step 6: delete tailwind.config.js. Once everything is working, remove the old config file. All configuration now lives in your CSS file, which is cleaner and does not require a JavaScript runtime to parse. Performance improvements. Tailwind 4 builds are significantly faster than v3. The new engine can process large projects in milliseconds. Hot module replacement during development is near-instant. If you were experiencing slow builds with Tailwind 3 on large codebases, the upgrade alone may solve those issues. This migration is straightforward for most projects. The automatic upgrade tool handles 80% of the work. Budget a few hours for a small project, a day or two for a large one. The result is a cleaner configuration system, better performance, and access to powerful new features like container queries.