If you've been following the Tailwind CSS project, you already know version 4 is a significant departure from everything that came before it. No more tailwind.config.js. No PostCSS pipeline (unless you want one). Configuration lives in your CSS file via @theme — and the result is a much leaner, faster DX.
In this post I'll walk through how I migrated my SvelteKit portfolio to Tailwind v4, what broke, and what genuinely surprised me.
What Changed
Tailwind v4 moves from a JavaScript config to a CSS-native theme system. Your custom colours, fonts, and spacing live in a single @theme block inside your main stylesheet:
- Colours: defined as CSS custom properties (e.g. `--color-primary: #258cf4`)
- No more JIT — everything is JIT by default
- Vite plugin replaces the PostCSS plugin for most setups
- Utility names have been tightened: `bg-gradient-to-r` → `bg-linear-to-r`, `flex-grow` → `grow`
The Migration
Step 1 — Install the new packages
Remove `tailwindcss` + `autoprefixer` from your PostCSS config and install the Vite plugin:
Step 2 — Move your config to CSS
Everything in tailwind.config.js under theme.extend moves into an @theme block at the top of your app.css. Custom utilities live in @layer utilities.
Step 3 — Update class names
The linter (via the suggestCanonicalClasses rule) flags deprecated class names and suggests the v4 equivalents. Run through the warnings and batch-replace them.
"Migrating to Tailwind v4 took about two hours for a mid-sized SvelteKit app. The improved build speeds alone made it worthwhile."
Svelte 5 Compatibility
One thing that caught me off guard: Svelte 5's rune-based reactivity interacts with Tailwind's class-name scanning in subtle ways. Since Svelte 5 uses $derived and $state instead of reactive declarations, ensure your dynamic class strings are stable and not generated inside complex derived expressions that Tailwind can't statically scan.
The simple rule: keep dynamic classes in clearly-defined string expressions. Use lookup objects or template literals that Tailwind can scan at build time.
Conclusion
Tailwind v4 is faster, leaner, and more aligned with how CSS actually works. The migration has a few sharp edges but nothing insurmountable. If you're on SvelteKit, the combination of SvelteKit's lean runtime and Tailwind v4's build speed makes for an exceptionally fast development experience.
