Nâng cấp các dự án Tailwind CSS của bạn từ v3 lên v4.
Tailwind CSS v4.0 là một phiên bản chính mới của framework, vì vậy mặc dù chúng tôi đã làm việc rất chăm chỉ để giảm thiểu các thay đổi gây phá vỡ, một số cập nhật là cần thiết. Hướng dẫn này phác thảo tất cả các bước cần thiết để nâng cấp các dự án của bạn từ v3 lên v4.
Tailwind CSS v4.0 được thiết kế cho Safari 16.4+, Chrome 111+, và Firefox 128+. Nếu bạn cần hỗ trợ các trình duyệt cũ hơn, hãy gắn bó với v3.4 cho đến khi yêu cầu hỗ trợ trình duyệt của bạn thay đổi.
Nếu bạn muốn nâng cấp một dự án từ v3 lên v4, bạn có thể sử dụng công cụ nâng cấp của chúng tôi để thực hiện phần lớn công việc nặng nhọc cho bạn:
$ npx @tailwindcss/upgradeĐối với hầu hết các dự án, công cụ nâng cấp sẽ tự động hóa toàn bộ quá trình di chuyển bao gồm cập nhật các phụ thuộc của bạn, di chuyển tệp cấu hình của bạn sang CSS và xử lý mọi thay đổi đối với các tệp template của bạn.
Công cụ nâng cấp yêu cầu Node.js 20 trở lên, vì vậy hãy đảm bảo môi trường của bạn được cập nhật trước khi chạy nó.
Chúng tôi khuyên bạn nên chạy công cụ nâng cấp trong một nhánh mới, sau đó xem xét cẩn thận diff và kiểm tra dự án của bạn trong trình duyệt để đảm bảo tất cả các thay đổi đều chính xác. Bạn có thể cần phải tinh chỉnh một vài thứ bằng tay trong các dự án phức tạp, nhưng công cụ sẽ giúp bạn tiết kiệm rất nhiều thời gian dù thế nào đi nữa.
Cũng là một ý tưởng hay khi xem qua tất cả các thay đổi gây phá vỡ trong v4 và hiểu rõ những gì đã thay đổi, trong trường hợp có những thứ khác bạn cần cập nhật trong dự án của mình mà công cụ nâng cấp không bắt được.
Trong v3, gói tailwindcss là một plugin PostCSS, nhưng trong v4, plugin PostCSS nằm trong một gói @tailwindcss/postcss chuyên dụng.
Ngoài ra, trong v4, việc import và thêm tiền tố nhà cung cấp (vendor prefixing) hiện được xử lý tự động cho bạn, vì vậy bạn có thể xóa postcss-import và autoprefixer nếu chúng có trong dự án của bạn:
export default { plugins: { "postcss-import": {}, tailwindcss: {}, autoprefixer: {}, "@tailwindcss/postcss": {}, },};Nếu bạn đang sử dụng Vite, chúng tôi khuyên bạn nên di chuyển từ plugin PostCSS sang plugin Vite chuyên dụng mới của chúng tôi để cải thiện hiệu suất và trải nghiệm nhà phát triển tốt nhất:
import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({ plugins: [ tailwindcss(), ],});Trong v4, Tailwind CLI nằm trong một gói @tailwindcss/cli chuyên dụng. Cập nhật bất kỳ lệnh build nào của bạn để sử dụng gói mới thay thế:
npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.cssDưới đây là danh sách đầy đủ tất cả các thay đổi gây phá vỡ trong Tailwind CSS v4.0.
Công cụ nâng cấp của chúng tôi sẽ xử lý hầu hết các thay đổi này cho bạn một cách tự động, vì vậy chúng tôi thực sự khuyên bạn nên sử dụng nó nếu có thể.
Tailwind CSS v4.0 được thiết kế cho các trình duyệt hiện đại và nhắm mục tiêu Safari 16.4, Chrome 111, và Firefox 128. Chúng tôi phụ thuộc vào các tính năng CSS hiện đại như @property và color-mix() cho các tính năng cốt lõi của framework, và Tailwind CSS v4.0 sẽ không hoạt động trong các trình duyệt cũ hơn.
Nếu bạn cần hỗ trợ các trình duyệt cũ hơn, chúng tôi khuyên bạn nên gắn bó với v3.4 vào lúc này. Chúng tôi đang tích cực khám phá chế độ tương thích để giúp mọi người nâng cấp sớm hơn mà chúng tôi hy vọng sẽ chia sẻ thêm tin tức trong tương lai.
Trong v4, bạn import Tailwind bằng cách sử dụng câu lệnh @import CSS thông thường, không sử dụng các chỉ thị @tailwind bạn đã sử dụng trong v3:
@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";Chúng tôi đã xóa bất kỳ tiện ích nào đã bị phản đối trong v3 và không có tài liệu trong vài năm. Dưới đây là danh sách những gì đã bị xóa cùng với giải pháp thay thế hiện đại:
| Đã phản đối | Thay thế |
|---|---|
bg-opacity-* | Sử dụng modifier độ mờ như bg-black/50 |
text-opacity-* | Sử dụng modifier độ mờ như text-black/50 |
border-opacity-* | Sử dụng modifier độ mờ như border-black/50 |
divide-opacity-* | Sử dụng modifier độ mờ như divide-black/50 |
ring-opacity-* | Sử dụng modifier độ mờ như ring-black/50 |
placeholder-opacity-* | Sử dụng modifier độ mờ như placeholder-black/50 |
flex-shrink-* | shrink-* |
flex-grow-* | grow-* |
overflow-ellipsis | text-ellipsis |
decoration-slice | box-decoration-slice |
decoration-clone | box-decoration-clone |
Chúng tôi đã đổi tên các tiện ích sau trong v4 để làm cho chúng nhất quán và dễ đoán hơn:
| v3 | v4 |
|---|---|
shadow-sm | shadow-xs |
shadow | shadow-sm |
drop-shadow-sm | drop-shadow-xs |
drop-shadow | drop-shadow-sm |
blur-sm | blur-xs |
blur | blur-sm |
backdrop-blur-sm | backdrop-blur-xs |
backdrop-blur | backdrop-blur-sm |
rounded-sm | rounded-xs |
rounded | rounded-sm |
outline-none | outline-hidden |
ring | ring-3 |
Chúng tôi đã đổi tên các thang đo bóng, bán kính và độ mờ mặc định để đảm bảo mọi tiện ích đều có giá trị được đặt tên. Các phiên bản "trần" vẫn hoạt động để tương thích ngược, nhưng các tiện ích <utility>-sm sẽ trông khác trừ khi được cập nhật thành các phiên bản <utility>-xs tương ứng của chúng.
Để cập nhật dự án của bạn cho những thay đổi này, hãy thay thế tất cả các tiện ích v3 bằng các phiên bản v4 của chúng:
<input class="shadow-sm" /><input class="shadow-xs" /><input class="shadow" /><input class="shadow-sm" />Tiện ích outline hiện đặt outline-width: 1px theo mặc định để nhất quán hơn với các tiện ích border và ring. Hơn nữa, tất cả các tiện ích outline-<number> mặc định outline-style thành solid, loại bỏ sự cần thiết phải kết hợp chúng với outline:
<input class="outline outline-2" /><input class="outline-2" />Tiện ích outline-none trước đây thực sự không đặt outline-style: none, mà thay vào đó đặt một outline vô hình vẫn sẽ hiển thị trong chế độ forced colors vì lý do truy cập.
Để làm rõ điều này hơn, chúng tôi đã đổi tên tiện ích này thành outline-hidden và thêm một tiện ích outline-none mới thực sự đặt outline-style: none.
Để cập nhật dự án của bạn cho thay đổi này, hãy thay thế bất kỳ việc sử dụng outline-none nào bằng outline-hidden:
<input class="focus:outline-none" /><input class="focus:outline-hidden" />Trong v3, tiện ích ring đã thêm một ring 3px. Chúng tôi đã thay đổi điều này trong v4 thành 1px để làm cho nó nhất quán với border và outline.
Để cập nhật dự án của bạn cho thay đổi này, hãy thay thế bất kỳ việc sử dụng ring nào bằng ring-3:
<input class="ring ring-blue-500" /><input class="ring-3 ring-blue-500" />Chúng tôi đã thay đổi selector được sử dụng bởi các tiện ích space-x-* và space-y-* để giải quyết các vấn đề hiệu suất nghiêm trọng trên các trang lớn:
/* Trước đây */.space-y-4 > :not([hidden]) ~ :not([hidden]) { margin-top: 1rem;}/* Bây giờ */.space-y-4 > :not(:last-child) { margin-bottom: 1rem;}Bạn có thể thấy những thay đổi trong dự án của mình nếu bạn đã từng sử dụng các tiện ích này với các phần tử nội dòng (inline), hoặc nếu bạn đang thêm các lề khác vào các phần tử con để tinh chỉnh khoảng cách của chúng.
Nếu thay đổi này gây ra bất kỳ vấn đề nào trong dự án của bạn, chúng tôi khuyên bạn nên di chuyển sang bố cục flex hoặc grid và sử dụng gap thay thế:
<div class="space-y-4 p-4"><div class="flex flex-col gap-4 p-4"> <label for="name">Name</label> <input type="text" name="name" /></div>Trong v3, việc ghi đè một phần của gradient bằng một biến thể sẽ "đặt lại" toàn bộ gradient, vì vậy trong ví dụ này, màu to-* sẽ trong suốt ở chế độ tối thay vì màu vàng:
<div class="bg-gradient-to-r from-red-500 to-yellow-400 dark:from-blue-500"> <!-- ... --></div>Trong v4, các giá trị này được bảo tồn, điều này nhất quán hơn với cách các tiện ích khác trong Tailwind hoạt động.
Điều này có nghĩa là bạn có thể cần phải sử dụng via-none một cách rõ ràng nếu bạn muốn "hủy đặt" một gradient ba điểm dừng trở lại gradient hai điểm dừng ở một trạng thái cụ thể:
<div class="bg-linear-to-r from-red-500 via-orange-400 to-yellow-400 dark:via-none dark:from-blue-500 dark:to-teal-400"> <!-- ... --></div>Trong v3, tiện ích container có một số tùy chọn cấu hình như center và padding không còn tồn tại trong v4.
Để tùy chỉnh tiện ích container trong v4, hãy mở rộng nó bằng cách sử dụng chỉ thị @utility:
@utility container { margin-inline: auto; padding-inline: 2rem;}Trong v3, các tiện ích border-* và divide-* sử dụng màu gray-200 đã cấu hình của bạn theo mặc định. Chúng tôi đã thay đổi điều này thành currentColor trong v4 để làm cho Tailwind ít áp đặt hơn và khớp với mặc định của trình duyệt.
Để cập nhật dự án của bạn cho thay đổi này, hãy đảm bảo bạn chỉ định một màu ở bất kỳ đâu bạn đang sử dụng tiện ích border-* hoặc divide-*:
<div class="border border-gray-200 px-2 py-3 ..."> <!-- ... --></div>Ngoài ra, hãy thêm các kiểu cơ sở này vào dự án của bạn để bảo tồn hành vi v3:
@layer base { *, ::after, ::before, ::backdrop, ::file-selector-button { border-color: var(--color-gray-200, currentColor); }}Chúng tôi đã thay đổi độ rộng của tiện ích ring từ 3px thành 1px và thay đổi màu mặc định từ blue-500 thành currentColor để làm cho mọi thứ nhất quán hơn với các tiện ích border-*, divide-* và outline-*.
Để cập nhật dự án của bạn cho những thay đổi này, hãy thay thế bất kỳ việc sử dụng ring nào bằng ring-3:
<button class="focus:ring ..."><button class="focus:ring-3 ..."> <!-- ... --></button>Sau đó, hãy đảm bảo thêm ring-blue-500 ở bất kỳ đâu bạn phụ thuộc vào màu ring mặc định:
<button class="focus:ring-3 focus:ring-blue-500 ..."> <!-- ... --></button>Ngoài ra, hãy thêm các biến theme này vào CSS của bạn để bảo tồn hành vi v3:
@theme { --default-ring-width: 3px; --default-ring-color: var(--color-blue-500);}Tuy nhiên, lưu ý rằng các biến này chỉ được hỗ trợ vì lý do tương thích và không được coi là cách sử dụng thành ngữ của Tailwind CSS v4.0.
Chúng tôi đã thực hiện một vài thay đổi nhỏ đối với các kiểu cơ sở trong Preflight trong v4:
Trong v3, văn bản placeholder sử dụng màu gray-400 đã cấu hình của bạn theo mặc định. Chúng tôi đã đơn giản hóa điều này trong v4 để chỉ sử dụng màu văn bản hiện tại ở độ mờ 50%.
Bạn có thể thậm chí sẽ không nhận thấy sự thay đổi này (nó thậm chí có thể làm cho dự án của bạn trông đẹp hơn), nhưng nếu bạn muốn bảo tồn hành vi v3, hãy thêm CSS này vào dự án của bạn:
@layer base { input::placeholder, textarea::placeholder { color: var(--color-gray-400); }}Các nút hiện sử dụng cursor: default thay vì cursor: pointer để khớp với hành vi trình duyệt mặc định.
Nếu bạn muốn tiếp tục sử dụng cursor: pointer theo mặc định, hãy thêm các kiểu cơ sở này vào CSS của bạn:
@layer base { button:not(:disabled), [role="button"]:not(:disabled) { cursor: pointer; }}Preflight hiện đặt lại lề trên các phần tử <dialog> để nhất quán với cách các phần tử khác được đặt lại.
Nếu bạn vẫn muốn các hộp thoại được căn giữa theo mặc định, hãy thêm CSS này vào dự án của bạn:
@layer base { dialog { margin: auto; }}Các lớp hiển thị như block hoặc flex không còn được ưu tiên hơn thuộc tính hidden trên một phần tử. Xóa thuộc tính hidden nếu bạn muốn một phần tử hiển thị cho người dùng. Lưu ý rằng điều này không áp dụng cho hidden="until-found".
Các tiền tố hiện trông giống như các biến thể và luôn ở đầu tên lớp:
<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600"> <!-- ... --></div>Khi sử dụng tiền tố, bạn vẫn nên cấu hình các biến theme của mình như thể bạn không sử dụng tiền tố:
@import "tailwindcss" prefix(tw);@theme { --font-display: "Satoshi", "sans-serif"; --breakpoint-3xl: 120rem; --color-avocado-100: oklch(0.99 0 0); --color-avocado-200: oklch(0.98 0.04 113.22); --color-avocado-300: oklch(0.94 0.11 115.03); /* ... */}Các biến CSS được tạo sẽ bao gồm tiền tố để tránh xung đột với bất kỳ biến hiện có nào trong dự án của bạn:
:root { --tw-font-display: "Satoshi", "sans-serif"; --tw-breakpoint-3xl: 120rem; --tw-color-avocado-100: oklch(0.99 0 0); --tw-color-avocado-200: oklch(0.98 0.04 113.22); --tw-color-avocado-300: oklch(0.94 0.11 115.03); /* ... */}Trong v3, bạn có thể đánh dấu một tiện ích là quan trọng bằng cách đặt dấu ! ở đầu tên tiện ích (nhưng sau bất kỳ biến thể nào). Trong v4, bạn nên đặt dấu ! ở cuối tên lớp thay thế:
<div class="flex! bg-red-500! hover:bg-red-600/50!"> <!-- ... --></div>Cách cũ vẫn được hỗ trợ để tương thích nhưng đã bị phản đối.
Trong v3, bất kỳ lớp tùy chỉnh nào bạn đã xác định trong @layer utilities hoặc @layer components sẽ được Tailwind chọn làm lớp tiện ích thực sự và sẽ tự động hoạt động với các biến thể như hover, focus hoặc lg với sự khác biệt là @layer components sẽ luôn xuất hiện trước trong stylesheet được tạo.
Trong v4, chúng tôi đang sử dụng các lớp cascade gốc và không còn chiếm đoạt quy tắc at-rule @layer nữa, vì vậy chúng tôi đã giới thiệu API @utility như một sự thay thế:
@layer utilities { .tab-4 { tab-size: 4; }}@utility tab-4 { tab-size: 4;}Các tiện ích tùy chỉnh hiện cũng được sắp xếp dựa trên lượng thuộc tính mà chúng xác định. Điều này có nghĩa là các tiện ích thành phần như .btn này có thể bị ghi đè bởi các tiện ích Tailwind khác mà không cần cấu hình thêm:
@layer components { .btn { border-radius: 0.5rem; padding: 0.5rem 1rem; background-color: ButtonFace; }}@utility btn { border-radius: 0.5rem; padding: 0.5rem 1rem; background-color: ButtonFace;}Tìm hiểu thêm về đăng ký các tiện ích tùy chỉnh trong tài liệu thêm các tiện ích tùy chỉnh.
Trong v3, các biến thể xếp chồng được áp dụng từ phải sang trái, nhưng trong v4, chúng tôi đã cập nhật chúng để áp dụng từ trái sang phải để trông giống cú pháp CSS hơn.
Để cập nhật dự án của bạn cho thay đổi này, hãy đảo ngược thứ tự của bất kỳ biến thể xếp chồng nhạy cảm với thứ tự nào trong dự án của bạn:
<ul class="py-4 first:*:pt-0 last:*:pb-0"><ul class="py-4 *:first:pt-0 *:last:pb-0"> <li>One</li> <li>Two</li> <li>Three</li></ul>Bạn có thể có rất ít trong số này nếu có — biến thể con trực tiếp (*) và bất kỳ biến thể plugin typography nào (prose-headings) là những biến thể có khả năng nhất bạn có thể đang sử dụng, và ngay cả khi đó chỉ là nếu bạn đã xếp chồng chúng với các biến thể khác.
Trong v3, bạn có thể sử dụng các biến CSS làm giá trị tùy ý mà không cần var(), nhưng các cập nhật gần đây cho CSS có nghĩa là điều này thường có thể mơ hồ, vì vậy chúng tôi đã thay đổi cú pháp cho điều này trong v4 để sử dụng dấu ngoặc đơn thay vì dấu ngoặc vuông.
Để cập nhật dự án của bạn cho thay đổi này, hãy thay thế việc sử dụng cú pháp viết tắt biến cũ bằng cú pháp viết tắt biến mới:
<div class="bg-[--brand-color]"></div><div class="bg-(--brand-color)"></div>Dấu phẩy trước đây đã được thay thế bằng khoảng trắng trong các tiện ích grid-cols-*, grid-rows-* và object-* bên trong các giá trị tùy ý. Hành vi đặc biệt này tồn tại trong Tailwind CSS v3 để tương thích với v2. Khả năng tương thích này không còn tồn tại trong v4.0 và dấu gạch dưới phải được sử dụng để đại diện cho khoảng trắng.
Để cập nhật dự án của bạn cho thay đổi này, hãy thay thế việc sử dụng dấu phẩy được dự định là khoảng trắng bằng dấu gạch dưới:
<div class="grid-cols-[max-content,auto]"></div><div class="grid-cols-[max-content_auto]"></div>Trong v4, chúng tôi đã cập nhật biến thể hover để chỉ áp dụng khi thiết bị đầu vào chính hỗ trợ hover:
@media (hover: hover) { .hover\:underline:hover { text-decoration: underline; }}Điều này có thể tạo ra vấn đề nếu bạn đã xây dựng trang web của mình theo cách phụ thuộc vào các thiết bị cảm ứng kích hoạt hover khi chạm. Nếu đây là vấn đề đối với bạn, bạn có thể ghi đè biến thể hover bằng biến thể của riêng bạn sử dụng triển khai cũ:
@custom-variant hover (&:hover);Tuy nhiên, nói chung, chúng tôi khuyên bạn nên coi chức năng hover là một cải tiến và không phụ thuộc vào nó để trang web của bạn hoạt động vì các thiết bị cảm ứng không thực sự có khả năng hover.
Các tiện ích transition và transition-color hiện bao gồm thuộc tính outline-color.
Điều này có nghĩa là nếu bạn đang thêm một outline với màu tùy chỉnh khi focus, bạn sẽ thấy màu chuyển tiếp từ màu mặc định. Để tránh điều này, hãy đảm bảo bạn đặt màu outline vô điều kiện hoặc đặt rõ ràng cho cả hai trạng thái:
<button class="transition hover:outline-2 hover:outline-cyan-500"></button><button class="outline-cyan-500 transition hover:outline-2"></button>Trong v3, có một tùy chọn corePlugins bạn có thể sử dụng để vô hiệu hóa hoàn toàn một số tiện ích nhất định trong framework. Điều này không còn được hỗ trợ trong v4.
Vì v4 bao gồm các biến CSS cho tất cả các giá trị theme của bạn, chúng tôi khuyên bạn nên sử dụng các biến đó thay vì hàm theme() bất cứ khi nào có thể:
.my-class { background-color: theme(colors.red.500); background-color: var(--color-red-500);}Đối với các trường hợp bạn vẫn cần sử dụng hàm theme() (như trong media queries nơi các biến CSS không được hỗ trợ), bạn nên sử dụng tên biến CSS thay vì ký hiệu dấu chấm cũ:
@media (width >= theme(screens.xl)) {@media (width >= theme(--breakpoint-xl)) { /* ... */}Các tệp cấu hình JavaScript vẫn được hỗ trợ để tương thích ngược, nhưng chúng không còn được phát hiện tự động trong v4.
Nếu bạn vẫn cần sử dụng tệp cấu hình JavaScript, bạn có thể tải nó một cách rõ ràng bằng cách sử dụng chỉ thị @config:
@config "../../tailwind.config.js";Các tùy chọn corePlugins, safelist và separator từ cấu hình dựa trên JavaScript không được hỗ trợ trong v4.0. Để safelist các tiện ích trong v4, hãy sử dụng @source inline().
Trong v3, chúng tôi đã xuất một hàm resolveConfig mà bạn có thể sử dụng để biến cấu hình dựa trên JavaScript của mình thành một đối tượng phẳng mà bạn có thể sử dụng trong JavaScript khác của mình.
Chúng tôi đã xóa điều này trong v4 với hy vọng rằng mọi người có thể sử dụng trực tiếp các biến CSS mà chúng tôi tạo ra thay thế, điều này đơn giản hơn nhiều và sẽ giảm đáng kể kích thước gói của bạn.
Ví dụ, thư viện Motion phổ biến cho React cho phép bạn tạo hoạt ảnh đến và đi từ các giá trị biến CSS:
<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />Nếu bạn cần quyền truy cập vào giá trị biến CSS đã giải quyết trong JS, bạn có thể sử dụng getComputedStyle để lấy giá trị của một biến theme trên document root:
let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");Trong v4, các stylesheet được đóng gói riêng biệt với tệp CSS chính của bạn (ví dụ: tệp CSS modules, khối <style> trong Vue, Svelte hoặc Astro, v.v.) không có quyền truy cập vào các biến theme, tiện ích tùy chỉnh và biến thể tùy chỉnh được xác định trong các tệp khác.
Để làm cho các định nghĩa này có sẵn trong các ngữ cảnh này, hãy sử dụng @reference để import chúng mà không sao chép bất kỳ CSS nào trong gói của bạn:
<template> <h1>Hello world!</h1></template><style> @reference "../../app.css"; h1 { @apply text-2xl font-bold text-red-500; }</style>Ngoài ra, bạn có thể sử dụng trực tiếp các biến theme CSS của mình thay vì sử dụng @apply hoàn toàn, điều này cũng sẽ cải thiện hiệu suất vì Tailwind sẽ không cần xử lý các kiểu này:
<template> <h1>Hello world!</h1></template><style> h1 { color: var(--text-red-500); }</style>Bạn có thể tìm thêm tài liệu về sử dụng Tailwind với CSS modules.
Tailwind CSS v4.0 không được thiết kế để sử dụng với các bộ tiền xử lý CSS như Sass, Less hoặc Stylus. Hãy coi chính Tailwind CSS là bộ tiền xử lý của bạn — bạn không nên sử dụng Tailwind với Sass vì lý do tương tự như bạn sẽ không sử dụng Sass với Stylus. Do đó, không thể sử dụng Sass, Less hoặc Stylus cho các stylesheet hoặc khối <style> của bạn trong Vue, Svelte, Astro, v.v.
Tìm hiểu thêm trong tài liệu tương thích.