Recommended Free Tools
For a Vite project, migrate to Tailwind CSS v4 with the dedicated @tailwindcss/vite plugin. For a project already built around PostCSS, use @tailwindcss/postcss instead. Either way, replace the old Tailwind directives in your CSS entry file with @import "tailwindcss";, then review the migration changes and test the rendered site—not just whether the build succeeds.
Choose the integration that matches your build pipeline
Tailwind’s upgrade guide recommends its dedicated Vite plugin for Vite projects, describing it as the more seamless integration for several Vite-based frameworks. It specifically recommends moving from the PostCSS plugin to the Vite plugin when using Vite. If your framework has its own Tailwind instructions, follow those as well.
As an Amazon Associate I earn from qualifying purchases.
| Project pipeline | Tailwind integration | CSS entry |
|---|---|---|
| Vite | @tailwindcss/vite |
@import "tailwindcss"; |
| PostCSS-driven integration that is not using Vite’s recommended plugin path | @tailwindcss/postcss, with postcss |
@import "tailwindcss"; |
In v4, the PostCSS integration lives in its own package. A v3 configuration that used tailwindcss itself as the PostCSS plugin must be updated.
Prepare the migration
- Check browser requirements. Tailwind’s upgrade guide says v4 is designed for Safari 16.4 or later, Chrome 111 or later, and Firefox 128 or later. These are the minimum browser targets stated by Tailwind’s current guidance, not general browser-market statistics. If your project must support older browsers, the guide recommends staying on v3.4.
- Create a branch. Keep the migration isolated so you can review changes and revert if necessary.
- Run the upgrade tool for a typical v3-to-v4 migration. Use
npx @tailwindcss/upgrade. Tailwind states that this tool requires Node.js 20 or higher; that requirement applies to the upgrade tool, not necessarily to every Tailwind v4 project. - Inspect the diff. The tool can update dependencies, move configuration into CSS, and change templates, but project-specific changes may still need manual work.
Configure the Vite integration
Install tailwindcss and @tailwindcss/vite, register the Tailwind plugin in your Vite configuration, and import Tailwind in the CSS entry file. The example below shows the relevant shape of a TypeScript Vite configuration; retain any other plugins and settings your project needs.
#1 Best Overall
import { defineConfig } from "vite"
import tailwindcss from "@tailwindcss/vite"
export default defineConfig({
plugins: [
tailwindcss(),
],
})In the CSS file your app loads, replace the old Tailwind directives with:
@import "tailwindcss";If your project uses a framework-specific Vite setup, check its Tailwind instructions before applying a generic configuration.
Configure the PostCSS integration
For a PostCSS pipeline, install tailwindcss, @tailwindcss/postcss, and postcss. Configure the dedicated Tailwind PostCSS plugin in your project’s PostCSS configuration. For example, a JavaScript PostCSS config can use:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
export default {
plugins: {
"@tailwindcss/postcss": {},
},
}Then put @import "tailwindcss"; in the CSS entry file processed by that pipeline. The exact configuration-file format depends on the project; preserve other PostCSS plugins that the application still needs.
Replace v3 CSS directives and review configuration
The v3 entry pattern used separate directives. In v4, replace them with a regular CSS import:
/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* v4 */
@import "tailwindcss";JavaScript configuration files remain supported for backward compatibility, but Tailwind no longer detects them automatically. If you still rely on one, load it explicitly with @config. Also check for legacy options: corePlugins, safelist, and separator are not supported in v4.
Tailwind v4 handles imports and vendor prefixing automatically, so the upgrade guide says postcss-import and autoprefixer can be removed from the described setup. Before removing them, check whether other parts of your build use those shared plugins.
Inspect styles affected by changed defaults
A successful build does not establish that the migrated site looks or behaves the same. Review styles that depend on v3 defaults and ordering, including these documented changes:
- Border color: The default changed from the configured gray-200 behavior in v3 to
currentColorin v4. Add explicit border colors where the old appearance is required, or use Tailwind’s documented compatibility CSS if intentionally preserving that default. - Stacked variants: Their order changed from right-to-left to left-to-right. Check combinations whose result depends on variant order.
- Utility names and defaults: Some shadow, radius, blur, and outline utilities changed. Use the full upgrade guide to identify affected utilities; these examples are not an exhaustive list.
- CSS preprocessors: Tailwind v4 is not designed for Sass, Less, or Stylus preprocessing. Projects relying on those preprocessors need to account for that compatibility constraint.
Verify the migration in the browser
Review the official breaking-change list, then exercise representative pages and states in a browser. Include pages that use custom configuration, stacked variants, borders, shadows, radii, blur, and outlines. Check responsive and interactive states as well as the initial page view. Resolve visual or functional differences before treating the migration as complete.
Tailwind’s guidance calls for reviewing the upgrade changes and testing in a browser. The upgrade tool automates parts of the work; it does not guarantee a correct visual result.
Quick Recap
Official migration references
- Tailwind CSS v4 upgrade guide
- Tailwind CSS installation with Vite
- Tailwind CSS installation with PostCSS
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
