Tailwind v4: Những thay đổi quan trọng và cách migrate

Tailwind CSS v4 không chỉ là version bump — đây là rewrite hoàn toàn. Engine mới viết bằng Rust (Oxide), config chuyển từ JavaScript sang CSS-first, và nhiều breaking changes cần biết trước khi migrate.

Những thay đổi lớn nhất

1. CSS-first configuration

Không còn tailwind.config.js. Mọi config giờ nằm trong CSS:

/* app.css — thay thế tailwind.config.js */
@import "tailwindcss";

@theme {
  --color-primary: oklch(65% 0.25 260);
  --color-surface: oklch(98% 0.01 260);
  --font-sans: "Inter", sans-serif;
  --breakpoint-xs: 30rem;
  --radius-lg: 1rem;
  --shadow-card: 0 2px 12px oklch(0% 0 0 / 0.08);
}

/* Source detection tự động — không cần content config */

No more content: ['./src/**/*.tsx'] — Tailwind v4 tự detect source files.

2. Composable variants

Variants giờ composable tự do hơn. Bạn có thể stack variants mà trước đây không được. Container queries cũng built-in với syntax @container và @sm:, @lg: prefixes.

3. Performance: 10x faster

Oxide engine (Rust) build nhanh hơn 10x so với v3. Full rebuild của large project từ ~500ms xuống ~50ms. Incremental builds gần như instant.

4. Modern CSS output

v4 output native CSS nesting, oklch() colors, @layer — không còn flat CSS với thousands of utility classes. Bundle size nhỏ hơn đáng kể.

Breaking changes cần biết

• @apply vẫn hoạt động nhưng discouraged — dùng component approach thay thế.
• Một số utility đổi tên: bg-opacity-* → dùng bg-black/50 syntax.
• Plugin API thay đổi — plugins v3 cần update.
• darkMode: 'class' giờ là default behavior.
• Colors chuyển sang oklch — nếu bạn override colors, nên dùng oklch.

Migration từ v3

Tailwind cung cấp codemod tự động:

npx @tailwindcss/upgrade

Codemod sẽ:

1. Convert tailwind.config.js thành @theme block trong CSS.
2. Update deprecated utilities.
3. Migrate PostCSS config.

Sau khi chạy codemod, review manually — check custom plugins, verify color output (oklch vs rgb), test dark mode behavior.

Có nên migrate ngay?

Nếu project mới — dùng v4 luôn. Nếu project đang chạy v3 — migrate khi có thời gian. v3 vẫn maintained. Ưu tiên migrate nếu bạn cần performance improvement hoặc muốn dùng container queries built-in.

Kết

Tailwind v4 là bước tiến lớn — CSS-first config, Rust engine, modern CSS output. Migration path rõ ràng với codemod. Đây là thời điểm tốt để explore v4 trên side project trước khi roll out cho production.