Tailwind CSS v4 is a ground-up rewrite of the framework that introduces a CSS-first configuration approach, a new high-performance engine built on Lightning CSS, and significant API changes that affect how you configure and use Tailwind in your projects. Muhammad Sufyan of Sufyan Frontend has migrated projects to Tailwind v4 and shares this comprehensive guide to what changed and how to migrate.
The New CSS-First Configuration System
The most visible change in Tailwind CSS v4 is the elimination of the JavaScript configuration file for most use cases. Instead of tailwind.config.ts, you configure your design tokens directly in your CSS file using @theme and standard CSS custom properties. This makes configuration feel more native to the web platform and eliminates the build step needed to process the config file.
/* globals.css — Tailwind v4 configuration */
@import "tailwindcss";
@theme {
--color-primary: #38bdf8;
--color-accent: #818cf8;
--font-sans: "Inter", sans-serif;
--radius-card: 1rem;
}These CSS variables are automatically converted to utility classes you can use in your markup — text-primary, bg-accent, rounded-card etc. The approach is more transparent and easier for designers to understand, since the design tokens live in a CSS file rather than a JavaScript module.
The Lightning CSS Engine
Tailwind CSS v4 uses Lightning CSS as its underlying CSS processor, replacing PostCSS for most tasks. Lightning CSS is written in Rust and is dramatically faster than the JavaScript-based PostCSS pipeline. The result is near-instant CSS compilation even for large projects, which noticeably speeds up both development hot reloads and production builds.
- ▸Lightning CSS — Rust-based processor replacing PostCSS for faster builds
- ▸Automatic vendor prefixing — no need for Autoprefixer as a separate plugin
- ▸Native CSS nesting support — use modern CSS nesting in your stylesheets
- ▸Container queries — first-class support without plugins
Breaking Changes and Migration Tips
Migrating from Tailwind v3 to v4 requires updating your configuration from JavaScript to CSS, reviewing any custom plugins that depended on the JavaScript config API, and checking that third-party component libraries you use are compatible. For most projects, the migration is straightforward and the performance improvements make it well worth the effort.
Conclusion
Tailwind CSS v4 is a significant improvement in every measurable dimension — faster builds, a more elegant configuration system, and better alignment with modern CSS standards. Muhammad Sufyan uses Tailwind CSS v4 on new projects and recommends the upgrade to any team currently on v3. For more frontend tooling insights from Sufyan Frontend Developer, visit https://sufyan-frontend.vercel.app.