Nâng cấp dự án mới lên Tailwind v4 ngay hôm nay. Với dự án v3 hiện có: chạy công cụ migration tự động trên một branch riêng — phần lớn các thay đổi mang tính cơ học, nhưng có những breaking change thực sự cần bạn xem xét kỹ. v4 đã ổn định trên production từ v4.1 (tháng 4 năm 2025). Lưu ý cứng: nếu bạn vẫn cần hỗ trợ Safari < 16.4, Chrome < 111, hoặc Firefox < 128, hãy giữ nguyên v3.4 cho đến khi analytics của bạn cho thấy những browser đó không còn đáng kể nữa.

Bài viết này dành cho ai

Các developer đang có dự án Tailwind v3 và đang cân nhắc có nên chuyển sang v4 không. Nếu bạn đang bắt đầu dự án mới, v4 là lựa chọn hiển nhiên và bài review này không đề cập đến trường hợp đó. Mọi nội dung bên dưới đều giả định bạn đang có một codebase v3 đang chạy và muốn biết việc nâng cấp thực sự tốn bao nhiêu công sức.

Chúng tôi đã kiểm thử gì

Tailwind v4.2 so với v3.4.17, dựa trên benchmark từ thông báo chính thức của v4 chạy trên dự án Catalyst của Tailwind Labs (phần cứng Apple M-series). Kiểm tra hệ sinh thái được thực hiện vào tháng 5 năm 2026 dựa trên tài liệu đang hoạt động và các GitHub issue đang mở. Chúng tôi không tự chạy bộ benchmark — các con số bên dưới đến từ số liệu đã công bố của Tailwind Labs.

Cấu hình dựa trên CSS

Thay đổi lớn nhất về mặt khái niệm trong v4 là nơi bạn cấu hình Tailwind. File tailwind.config.js chuyển vào CSS.

v3:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: { brand: '#5c6ac4' },
    },
  },
}

v4:

@import "tailwindcss";

@theme {
  --color-brand: #5c6ac4;
}

Các directive @tailwind base, @tailwind components, @tailwind utilities không còn nữa. Một @import "tailwindcss" thay thế cả ba.

Nếu bạn cần giữ file JS config — cho việc chia sẻ trong monorepo hoặc tương thích plugin — nó vẫn hoạt động song song với CSS import:

@import "tailwindcss";
@config "../../tailwind.config.js";

corePlugins và separator không còn tồn tại và không có tương đương. safelist chuyển sang CSS: dùng @source inline() thay thế (xem upgrade guide). Nếu dự án của bạn phụ thuộc vào corePlugins hoặc separator, hãy dành thời gian đánh giá tác động trước khi nâng cấp. Utility resolveConfig() cũng bị xóa — nếu bất cứ thứ gì trong build pipeline của bạn gọi nó, cần phải sửa.

Nếu bạn vẫn đang cân nhắc liệu utility-first CSS có phải chiến lược đúng đắn về lâu dài không, Tailwind CSS vs CSS Modules so sánh chi phí thực tế tích lũy theo 1–3 năm.

Hiệu năng

v4 giới thiệu engine Oxide, được viết lại bằng Rust. Benchmark trên Catalyst:

Kịch bản	v3	v4	Cải thiện
Full build	378 ms	100 ms	Nhanh hơn 3.78×
Incremental (có CSS class mới)	44 ms	5 ms	Nhanh hơn 8.8×
Incremental (không có CSS mới)	35 ms	0.19 ms	Nhanh hơn 182×

Dòng thứ ba là cái bạn cảm nhận được trong công việc hàng ngày. Khi bạn sửa một file JSX mà không thêm class Tailwind mới nào, v4 bỏ qua hoàn toàn việc tái tạo CSS. Dưới một millisecond là tức thì trên thực tế. Với full build, nhanh hơn 3.78× có ý nghĩa nhất trên CI và khi cold start.

Một điểm đáng chú ý: blog của Tailwind mô tả engine là “viết lại bằng Rust,” nhưng tỷ lệ chính xác giữa Rust và các ngôn ngữ khác bên trong Oxide không được tài liệu hóa công khai. Các con số benchmark mới là thứ bạn nên dựa vào để đặt kỳ vọng.

Tailwind v4 — breaking changes

Upgrade guide đề cập tất cả những điều này. Dưới đây là những thay đổi có khả năng gây ra lỗi hiển thị trong một dự án thực tế.

Đổi tên utility class

Các scale shadow, blur và rounded dịch chuyển xuống một bậc:

Class v3	Tương đương v4
`shadow`	`shadow-sm`
`shadow-sm`	`shadow-xs`
`rounded`	`rounded-sm`
`rounded-sm`	`rounded-xs`
`blur`	`blur-sm`
`blur-sm`	`blur-xs`

Đây chính xác là loại thay đổi trông có vẻ đúng khi bạn kiểm tra từng component riêng lẻ nhưng sai khi nhìn chúng cạnh nhau. Đừng sửa tay — chạy công cụ migration tự động và review diff.

Ring mặc định thay đổi

v3: ring thêm ring 3px màu blue-500. v4: ring thêm ring 1px màu currentColor.

Nếu bạn dùng ring cho focus indicator bàn phím, style focus của bạn đã thay đổi — cả độ dày lẫn màu sắc. Kiểm tra các interactive element khi được focus.

Border color mặc định thay đổi

v3: border mặc định là gray-200. v4: border mặc định là currentColor.

Border trước đây subtle có thể trở nên đậm và nặng về mặt thị giác. Tìm các class border trần không có màu cụ thể và review chúng.

Xóa opacity utilities

bg-opacity-50, text-opacity-75, border-opacity-25 và các biến thể khác không còn nữa. Dùng cú pháp slash thay thế:

<!-- v3 -->
<div class="bg-black bg-opacity-50 text-white text-opacity-90">

<!-- v4 -->
<div class="bg-black/50 text-white/90">

Công cụ tự động có thể viết lại những cái này, nhưng nếu bạn có các chuỗi class được tạo động trong JavaScript, những cái đó cần xử lý thủ công.

Important modifier đảo chiều

!flex (bang prefix) → flex! (bang suffix). Cú pháp prefix v3 bị deprecated nhưng vẫn hoạt động để tương thích ngược — migrate khi thuận tiện.

Sass và Less bị loại bỏ

v4 đã bỏ hỗ trợ PostCSS cho Sass và Less. Nếu dự án của bạn chạy Tailwind qua bộ xử lý Sass hoặc Less, đường dẫn đó không còn nữa. Chỉ còn CSS thuần túy.

Yêu cầu browser tối thiểu

v4 phụ thuộc vào các tính năng CSS — cascade layers (@layer), color-mix(), logical properties — có mặt từ:

Safari 16.4+
Chrome 111+
Firefox 128+

Đây không phải khuyến nghị mềm từ caniuse; đây là yêu cầu cứng. v4.1 đã thêm fallback cho một số trường hợp, nhưng ngưỡng browser là thực. Kiểm tra analytics của bạn trước khi quyết định nâng cấp.

Hệ sinh thái

shadcn/ui

Hỗ trợ preview Tailwind v4 ra mắt vào tháng 2 năm 2025 — team shadcn/ui mô tả rõ đây là “preview đầu tiên về hỗ trợ Tailwind v4 và React 19,” không phải general availability. Tất cả component đã được cập nhật cho preview, CLI mặc định v4 cho các install mới, và màu sắc đã chuyển từ HSL sang OKLCH. Nếu bạn đang dùng dự án v3 với shadcn/ui, các component hiện tại vẫn tương thích ngược — bạn không cần nâng cấp shadcn chỉ vì muốn nâng cấp Tailwind. Với dự án mới, v4 là mặc định.

tailwindcss-animate bị deprecated trong v4. Tailwind nay đi kèm các animation CSS tích hợp sẵn bao gồm các use case tương tự.

Next.js

create-next-app --tailwind vẫn cài Tailwind v3.4.x tính đến giữa năm 2026. Tailwind v4 chưa phải mặc định trong scaffold của Next.js. Nếu bạn dựng dự án Next.js mới và muốn v4, hãy chạy công cụ nâng cấp sau khi scaffold.

Turbopack có vấn đề tương thích với v4 trong các release đầu — đã được xử lý trong v4.1. Webpack (bundler mặc định của Next.js) hoạt động tốt với v4. Nếu bạn đang dùng Turbopack và v4.0, nâng cấp lên v4.1+ sẽ giải quyết sự không ổn định. Để xem số liệu HMR và tốc độ build ngoài ngữ cảnh Next.js, hãy xem Turbopack vs Vite.

Dự án Vite hoạt động tốt với v4 từ v4.0. Nếu bạn đang đánh giá Tailwind v4 cho dự án mới, Vite là con đường ít trở ngại nhất — hướng dẫn Vite vs Webpack của chúng tôi giúp bạn đánh giá khi nào việc chuyển đổi build tool thực sự có giá trị.

Headless UI và Radix

Không có blocker nào liên quan đến v4. Cả hai thư viện đều unstyled — chúng không phụ thuộc vào Tailwind internals hay naming convention của class. Chúng hoạt động với bất kỳ phiên bản Tailwind nào bạn chạy.

Timeline ổn định

v4.0 ra mắt với các vấn đề production ảnh hưởng đến các team thực tế:

CSS không khớp giữa dev/prod trong setup Astro + Vite
@apply bị lỗi trong một số configuration
Edge case với dark mode
Lỗi tương thích Turbopack

Các team áp dụng v4.0 trong những tuần đầu đã gặp phải những vấn đề này. Một số đã downgrade về v3.4. Issue tracker trên GitHub của v4.0 phản ánh điều này — các thread thảo luận đáng đọc nếu bạn muốn biết cụ thể.

v4.1 (ngày 3 tháng 4 năm 2025) đã giải quyết các khiếu nại cốt lõi: fallback tương thích browser cho cascade layers, sửa độ tin cậy của @apply, sửa hành vi dark mode, cải thiện Turbopack. v4.2 tiếp tục cải thiện từ đó.

Nếu bạn đã thử v4 trong giai đoạn v4.0 và gặp sự cố, phiên bản hiện tại là một trải nghiệm khác. Khoảng cách v4.0 → v4.1 là giai đoạn ổn định hóa.

Ma trận quyết định nâng cấp

Tình huống	Khuyến nghị
Dự án mới, browser target hiện đại	Bắt đầu với v4. Không có lý do gì để bắt đầu với v3.
Dự án v3 hiện có, chỉ browser hiện đại	Nâng cấp. Dành riêng một branch, chạy công cụ migration, review các thay đổi shadow/ring/border. Dự trù nửa ngày cho dự án nhỏ, nhiều hơn cho dự án lớn.
Có traffic Safari < 16.4 / Chrome < 111 / Firefox < 128	Giữ v3.4 cho đến khi analytics của bạn loại bỏ được những browser đó.
Dự án dùng `corePlugins` hoặc `separator`	Đánh giá tác động trước khi nâng cấp. Những tính năng này không có tương đương trong v4. `safelist` chuyển sang `@source inline()` — rủi ro thấp hơn.
Dự án xử lý qua Sass hoặc Less	Tìm hiểu build path thay thế trước.
Đã thử v4.0 và gặp lỗi	Thử lại với v4.1+. Các vấn đề ban đầu đã được sửa.

Lưu ý

Công cụ migration tự động: npx @tailwindcss/upgrade chính thức xử lý hầu hết các thay đổi mang tính cơ học — đổi tên class, cập nhật syntax, migration config. Chạy nó trên một branch riêng và coi output là diff để review, không phải artifact sẵn sàng ship. Đặc biệt chú ý đến các chuỗi class được tạo động trong file JavaScript, mà công cụ có thể bỏ sót.

Sắc thái về Rust: Cách diễn đạt “viết lại bằng Rust” là mô tả của chính Tailwind Labs. Kiến trúc nội tại của Oxide — phần nào là Rust, phần nào không — không được tài liệu hóa chi tiết công khai. Các con số benchmark là thực và có thể tái tạo độc lập; chi tiết implementation không phải thứ chúng tôi xác minh.

Không có affiliate link: Tailwind Plus tồn tại — 500+ UI component block native v4, bộ Catalyst React component kit, mua một lần. Không có chương trình affiliate công khai đã được xác nhận cho Tailwind Plus. Không có link nào trong bài viết này đi qua affiliate tracker.

Tài liệu tham khảo

Thông báo Tailwind v4 — benchmark, Oxide engine, giới thiệu CSS-first config
Upgrade guide — danh sách đầy đủ breaking changes, công cụ migration tự động
Thông báo Tailwind v4.1 — sửa lỗi ổn định, fallback tương thích browser
shadcn/ui Tailwind v4 docs — cập nhật component, migration màu OKLCH
shadcn/ui changelog, tháng 2 năm 2025 — preview đầu tiên về hỗ trợ Tailwind v4 + React 19
Tailwind GitHub issue #16176 — báo cáo lỗi @apply
Tailwind GitHub discussion #16429 — thread thảo luận về độ ổn định v4
Thảo luận Next.js + Tailwind v4 — scaffold create-next-app vẫn dùng v3
Câu chuyện downgrade — các team thử v4.0 sớm và phải quay lại
Tailwind Plus — thư viện UI block thương mại