Tailwind CSS v3 → v4 Migration Helper
Paste your tailwind.config.js and get a CSS-first @theme block, a list of renamed and removed utilities, and a step-by-step upgrade checklist — with an optional live theme preview.
1 · Your v3 config
2 · Options
Everything runs locally in your browser. Nothing is uploaded.
3 · Quick actions
Renamed / removed utilities found in your markup
Theme preview (uses values parsed from your config)
Migrated theme
This preview is rendered with the colors, radii and shadows detected in your pasted config, so you can sanity-check the tokens before shipping.
brand-50-ish token if present, otherwise the first brand shade.Tailwind CSS v3 to v4 Migration Helper
Migrate your Tailwind CSS v3 project to Tailwind CSS v4 with a clear, practical workflow. Review configuration changes, identify common migration issues, understand the new CSS-first approach, and prepare your project for the latest Tailwind CSS architecture.
What Does the Tailwind v3 to v4 Migration Helper Do?
The Tailwind CSS v3 to v4 Migration Helper helps developers understand and organize the major changes involved when upgrading an existing Tailwind CSS v3 project to Tailwind CSS v4. It focuses on configuration, CSS imports, theme variables, plugins, utilities, compatibility issues, and common migration tasks.
Instead of treating the upgrade as a simple version change, use this helper as a structured checklist for reviewing your project before, during, and after migration.
What Is Tailwind CSS v3 to v4 Migration?
Tailwind CSS v4 introduced a major architectural change compared with Tailwind CSS v3. The newer version takes a more CSS-first approach and changes how developers define and customize many parts of a Tailwind project.
Because of these changes, upgrading an existing project may require more than changing a package version. Your CSS entry point, configuration, theme customization, plugins, custom utilities, and build setup may all need to be reviewed.
A Tailwind CSS v3 to v4 migration should therefore be approached as a controlled upgrade rather than a blind dependency update.
Why Migrate From Tailwind CSS v3 to v4?
Tailwind CSS v4 modernizes the framework and changes the way projects can define themes and use Tailwind features. For developers starting new projects, the newer architecture can provide a cleaner CSS-first workflow.
Existing applications may also benefit from the newer version, but the value of upgrading depends on the project's dependencies, customizations, build pipeline, and compatibility requirements.
Before migrating a production application, review the official migration documentation and test the upgrade in a separate branch or development environment.
Tailwind CSS v3 vs v4: What Changed?
| Area | Tailwind CSS v3 | Tailwind CSS v4 |
|---|---|---|
| Configuration | JavaScript configuration is commonly used | More CSS-first configuration |
| CSS Entry | Traditional Tailwind directives | Modern CSS import approach |
| Theme Customization | Often defined through configuration | CSS theme variables play a major role |
| Build Engine | Older Tailwind architecture | Newer high-performance engine |
| Migration | Existing v3 project | Requires compatibility review |
Tailwind CSS v4 Uses a More CSS-First Approach
One of the most important concepts when upgrading from Tailwind CSS v3 to v4 is the move toward a more CSS-first configuration model.
Instead of relying entirely on a large JavaScript configuration file, Tailwind CSS v4 allows more of the design system to be expressed directly in CSS through theme variables and related features.
This means developers migrating an existing application should carefully review values previously defined in their Tailwind configuration and decide how those design tokens should be represented in the new architecture.
Tailwind v3 Configuration Migration
Tailwind CSS v3 projects frequently contain a tailwind.config.js or related configuration file. It may contain custom colors, fonts, spacing values, breakpoints, plugins, variants, content paths, and other project-specific settings.
During migration, do not simply delete the configuration file and assume everything will work automatically. First inventory your custom settings and identify which ones are still required.
- Custom colors
- Typography settings
- Spacing and sizing tokens
- Custom breakpoints
- Animations
- Custom utilities
- Plugins
- Safelist entries
- Project content detection
Understanding the New Tailwind CSS v4 Import
Tailwind CSS v4 uses a modern CSS import approach. Developers migrating from v3 should review their existing Tailwind directives and update their stylesheet according to the v4 setup.
This is one of the first places where migration problems can appear. If your project still depends on the previous CSS entry structure, review the migration requirements before assuming the old stylesheet can be used unchanged.
What Happens to @tailwind Directives?
Tailwind CSS v3 commonly uses directives such as @tailwind base, @tailwind components, and @tailwind utilities.
Tailwind CSS v4 changes the recommended CSS entry approach. When migrating, inspect your existing stylesheet and update the Tailwind integration to the syntax expected by the v4 toolchain.
This is particularly important when a project contains additional custom CSS around the old Tailwind directives.
Tailwind CSS v3 to v4 Theme Migration
Custom themes are often one of the most important parts of a Tailwind project. A production application may contain dozens of custom colors, font families, spacing values, shadows, radii, and other design tokens.
When moving to Tailwind CSS v4, review these values and determine how they should be represented using the new CSS-first theme model.
This process is also a good opportunity to clean up unused design tokens and standardize inconsistent naming.
Tailwind v3 Custom Colors to v4
Custom colors are among the most frequently migrated design tokens. A v3 project may define brand colors, semantic colors, neutral colors, and complete color scales inside its configuration.
During a v4 migration, map your existing color system carefully and test every important component. Pay special attention to buttons, links, backgrounds, borders, alerts, forms, navigation, and dark mode.
A structured color system can also be generated with our Tailwind v4 Shade Generator when you need additional shades for a custom palette.
Tailwind CSS v3 to v4 Plugin Migration
Plugins can require additional attention during migration. A project may depend on official or third-party plugins that extend Tailwind with custom components, utilities, variants, or functionality.
Before upgrading a production application, verify that every important plugin supports your target Tailwind CSS version. Do not assume that a v3 plugin will behave identically under v4.
Custom Utilities During Migration
Many Tailwind projects contain custom utilities created for project-specific requirements. These utilities should be reviewed individually during the upgrade.
Check whether each custom utility is still necessary, whether its syntax remains compatible, and whether the same result can be achieved using the newer Tailwind CSS architecture.
Tailwind v4 Migration and Content Detection
Tailwind needs to know which project files contain classes that should be generated. Migration can therefore affect how your project detects source files and dynamically generated class names.
Review your templates, components, JavaScript files, framework integrations, and any dynamically constructed class names after upgrading.
Dynamic Tailwind Classes and Migration Problems
Dynamically constructing complete Tailwind class names can cause problems when the build system cannot detect the final class names in source files.
For example, generating class names by concatenating arbitrary color or spacing values can make it difficult for a utility scanner to determine which classes are required.
During migration, inspect components that build class names dynamically and replace fragile patterns with explicit class mappings where appropriate.
Tailwind CSS v3 to v4 Dark Mode Migration
Dark mode is another important area to test. Review your existing dark mode strategy, theme variables, component colors, borders, shadows, and text contrast.
Do not only check the main page. Test modals, dropdowns, forms, tables, alerts, cards, navigation, and interactive states in both light and dark themes.
Tailwind v4 Migration for Responsive Designs
Responsive interfaces should be tested across mobile, tablet, laptop, and large desktop layouts after migration.
A migration can expose problems that were not immediately visible on a desktop screen. Test responsive grids, spacing, typography, navigation, hidden elements, flex layouts, and breakpoint-dependent components.
Tailwind CSS v3 to v4 Migration Checklist
Keep the existing v3 project available while testing the upgrade.
Check Tailwind, build tools, plugins, and framework compatibility.
Inventory custom colors, fonts, utilities, plugins, and design tokens.
Move the project to the appropriate Tailwind v4 CSS setup.
Review custom design tokens and adapt them to the v4 architecture.
Check project-specific utilities and custom CSS.
Review buttons, forms, cards, navigation, modals, and tables.
Check mobile, tablet, desktop, and large-screen layouts.
Verify colors, contrast, surfaces, borders, and interactive states.
Run production builds and monitor the application after migration.
Common Tailwind v3 to v4 Migration Errors
Migration problems vary depending on how heavily a project customized Tailwind CSS. Some projects upgrade with minimal changes, while large applications can require substantial configuration and component updates.
- Old Tailwind directives remain in the main stylesheet.
- Custom configuration values are not migrated correctly.
- Third-party plugins are incompatible.
- Custom utilities no longer behave as expected.
- Dynamically generated classes are missed.
- Theme variables are not mapped correctly.
- Dark mode colors need adjustment.
- Responsive components require visual testing.
- Build tooling contains incompatible dependencies.
How to Migrate Tailwind CSS v3 to v4
- Back up your project. Create a Git branch or separate development copy before making changes.
- Audit the existing project. Identify custom configuration, plugins, utilities, themes, and build tools.
- Upgrade Tailwind. Move the project to the target Tailwind CSS v4 release and its required integration.
- Update your CSS setup. Replace the previous v3 Tailwind entry structure with the appropriate v4 approach.
- Review configuration. Migrate the design tokens and settings your application actually needs.
- Check plugins. Confirm that third-party integrations support your new version.
- Run the development build. Fix compilation and utility-generation issues before testing the UI.
- Test the interface. Check every major component, page, theme, and responsive breakpoint.
- Run the production build. Verify that the optimized build behaves correctly before deployment.
Should You Manually Migrate Tailwind v3 to v4?
Small projects can often be reviewed and migrated manually. Larger projects may benefit from using migration tooling together with a manual code review.
Automated migration can save time, but developers should still inspect the resulting code. Automated changes cannot understand every application-specific design decision, plugin dependency, dynamic class pattern, or custom component.
Tailwind CSS v4 Migration for Next.js
Next.js applications commonly use Tailwind CSS for component styling. When upgrading such a project, review the Tailwind integration, CSS entry file, build process, theme customization, and application components.
After migration, test both development and production builds. Pay particular attention to layouts that use server-rendered components, client components, dynamically generated classes, and reusable UI libraries.
Tailwind CSS v4 Migration for React
React projects should be checked component by component after migration. Verify utility classes, conditional class names, reusable components, responsive states, and theme behavior.
If your application uses a class-name utility or component library, verify that its Tailwind integration remains compatible with the new version.
Tailwind CSS v4 Migration for Vue
Vue projects should similarly review their Tailwind integration, CSS files, component templates, conditional classes, custom theme values, and build configuration.
How Long Does Tailwind v3 to v4 Migration Take?
Migration time depends heavily on project size and customization. A small project with minimal configuration may require relatively little work, while a large application with custom plugins, themes, utilities, and multiple frameworks can require significantly more testing.
The safest approach is to estimate the work after auditing your existing Tailwind configuration and dependencies rather than assuming every project will take the same amount of time.
Tailwind v3 to v4 Migration Best Practices
- Always create a backup or separate migration branch.
- Read the official migration documentation for your target release.
- Audit your existing configuration before changing it.
- Remove unused customizations where appropriate.
- Test third-party plugins individually.
- Check dynamic class generation.
- Test light and dark themes.
- Test all important responsive breakpoints.
- Run both development and production builds.
- Visually inspect important pages after migration.
Tailwind CSS v3 to v4 Migration Helper for Developers
The goal of a migration helper is not to replace developer judgment. Instead, it provides a structured way to identify the areas that deserve attention during an upgrade.
Use the helper to organize your migration tasks, compare your existing setup with the new architecture, identify likely compatibility issues, and create a repeatable migration process for future projects.
Related Tailwind and Color Tools
- Tailwind v4 Shade Generator
- Color Picker
- HEX to OKLCH Converter
- OKLCH Color Picker
- Color Contrast Checker
- APCA Contrast Checker
Frequently Asked Questions
What is the Tailwind CSS v3 to v4 Migration Helper?
It is a tool and reference workflow that helps developers review the major changes involved in upgrading a Tailwind CSS v3 project to Tailwind CSS v4.
Is Tailwind CSS v4 compatible with Tailwind CSS v3 projects?
Existing v3 projects can be migrated to v4, but the project should be reviewed for configuration, CSS, plugins, utilities, and other compatibility changes.
What is the biggest change from Tailwind v3 to v4?
One of the major changes is Tailwind CSS v4's more CSS-first approach to configuration and theming, along with changes to the framework's build architecture and setup.
Do I need to replace tailwind.config.js when migrating?
Not every project should be treated identically. Review the configuration and migrate the custom settings your project actually needs according to the Tailwind CSS v4 migration requirements.
What happened to @tailwind directives in Tailwind v4?
Tailwind CSS v4 uses a modern CSS import approach, so projects migrating from v3 should review and update their existing Tailwind stylesheet setup.
Can I migrate Tailwind CSS v3 to v4 automatically?
Migration tooling can automate parts of the upgrade, but developers should still review the resulting project, especially custom themes, plugins, utilities, and application-specific code.
Do Tailwind plugins need to be checked during migration?
Yes. Third-party plugins should be checked for compatibility with the Tailwind CSS version you are migrating to.
Will my Tailwind v3 custom colors work in v4?
Custom colors should be reviewed and mapped appropriately to the Tailwind CSS v4 theme and CSS-first architecture.
Can I migrate a large Tailwind project to v4?
Yes. Large projects can be migrated, but they require more careful auditing, testing, dependency checks, and component verification.
Should I test my website after Tailwind v4 migration?
Yes. Test important pages, components, responsive layouts, dark mode, forms, navigation, and production builds after migration.
Can I use this migration helper for Next.js?
Yes. The migration concepts can help developers review Tailwind integration in Next.js projects, including CSS setup, components, theme customization, and build configuration.
Can I use this migration helper for React?
Yes. React developers can use the helper to organize configuration, CSS, component, plugin, and responsive-layout checks during migration.
How do I migrate Tailwind CSS v3 to v4 safely?
Create a backup or migration branch, audit the project, update the Tailwind setup, review configuration and plugins, test components, run production builds, and verify the final interface before deployment.
Is Tailwind CSS v4 better than v3?
Tailwind CSS v4 introduces a newer architecture and CSS-first workflow. Whether it is better for a particular project depends on its requirements, dependencies, customization, and migration effort.
Where can I learn more about Tailwind CSS v4 migration?
The official Tailwind CSS documentation and migration guide should be used as the primary reference for version-specific migration instructions and compatibility details.
Final Thoughts
Moving from Tailwind CSS v3 to v4 is a significant upgrade for projects that rely heavily on custom configuration and extensions. The safest approach is to understand the architectural changes, audit your existing project, migrate only what you need, and test the application thoroughly.
The Tailwind CSS v3 to v4 Migration Helper gives developers a practical way to organize that process. Use it as a migration checklist, troubleshooting reference, and starting point before making changes to a production application.