مهاجرت به Tailwind CSS v4: موتور Oxide، تنظیمات CSS-First و بیلد سریع‌تر
نویسنده: آرش لطیفی
Tailwind v4 دیگه config جاوااسکریپتی نداره؛ همه‌چی رفته توی CSS با @theme. موتور جدید Oxide بیلد کامل رو تا ۵ برابر سریع‌تر می‌کنه. راهنمای گام‌به‌گام مهاجرت از v3 با جدول مقایسه، کد و تله‌ها.
چکیده (TL;DR): Tailwind v4 از یه موتور جدید به اسم Oxide (نوشته‌شده با Rust) استفاده می‌کنه که بیلد کامل رو تا ۵ برابر و بیلد افزایشی رو بیش از ۱۰۰ برابر سریع‌تر می‌کنه. مهم‌ترین تغییر برای تو: فایل
tailwind.config.jsدیگه نیست — همه‌ی تنظیمات می‌ره توی CSS با بلوک@theme. خود کلاس‌های utility تقریبا دست‌نخورده موندن، پس مهاجرت بیشتر درباره‌ی «پلاگین‌ها و config» هست تا «HTML». توی ۱۰ دقیقه تموم می‌شه.
وقتی Tailwind v4 آپدیت شد، بیشتر ما فکر کردیم «فقط یه نسخه‌ی جدید دیگه». ولی این مهاجرت با بقیه فرق داره: فلسفه‌ی پیکربندی کاملا عوض شده. اگه توی یه پروژه‌ی قدیمی با v3 مونده باشی، این مطلب دقیقا برای توئه — با استعاره و کد، نه با اصطلاحات قلمبه‌سلمبه.
چرا اصلا آپدیت کنیم؟ — جدول قبل و بعد
Oxide فقط یه «کمی سریع‌تر» نیست؛ یه مرتبهی بزرگی فرق داره. اعداد واقعی از پروژه‌های مهاجرت‌کرده:
| معیار | ادعای رسمی Tailwind | توضیح | |---|---|---| | بیلد کامل (full build) | تا ۵ برابر سریع‌تر | بسته به اندازه و پیچیدگی پروژه | | بیلد افزایشی (incremental) | بیش از ۱۰۰ برابر سریع‌تر | فقط برای کلاس‌هایی که واقعاً استفاده شده‌اند | | حجم CSS / مصرف حافظه | عدد رسمی منتشر نشده | کاملاً به ساختار پروژه بستگی دارد |
این اعداد را خود Tailwind در راهنمای ارتقا اعلام کرده. عدد دقیق پروژه‌ی خودت را خودت بساز: قبل و بعد pnpm build را زمان بگیر.
استعاره‌ش ساده‌ست: v3 هر بار یه کارگاه کامل رو از نو راه می‌نداخت که «کدوم کلاس‌ها استفاده شدن؟» رو بشمره؛ v4 با موتور Rust این شمارش رو در حد چند میلی‌ثانیه انجام می‌ده. نتیجه: توی پروژه‌ی بزرگ، F5 زدن و منتظر موندن دیگه تموم می‌شه.
نقشه‌ی راه: ۶ قدم مهاجرت
قدم ۱ — وابستگی‌ها رو آپدیت کن
اگه از @tailwindcss/vite استفاده می‌کنی، پلاگین قدیمی رو از vite.config.ts بردار و این رو بذار:
قدم ۲ — دستورات @tailwind رو عوض کن
قدم ۳ — config رو ببر توی CSS (مهم‌ترین قدم!)
تو v3 رنگ دلخواهت توی یه آبجکت جاوااسکریپت بود:
تو v4 این می‌شه CSS واقعی — با بلوک @theme:
دو نکته‌ی مهم:
- اسم‌ها صاف شدن:
colors.brand.lightقبلی حالا--color-brand-lightاست، نه--color-brand.light. - این‌ها CSS variable واقعی‌ان: می‌تونی بیرون از Tailwind هم استفاده‌شون کنی، توی inline style یا حتی با
getComputedStyleتو جاوااسکریپت.
قدم ۴ — پلاگین‌ها رو با @plugin صدا بزن
قدم ۵ — حالت dark رو درست کن
تو v3 می‌گفتی darkMode: "class". تو v4 دیفالت روی prefers-color-scheme است؛ اگه حالت کلاسی می‌خوای:
قدم ۶ — مسیرهای غیرعادی رو با @source بگو
اگه محتوای خارج از مسیرهای پیش‌فرض داری (مثلا فایل‌های توی یه پکیج دیگر):
جدول مقایسه‌ی سریع: چی عوض شد؟
| موضوع | v3 | v4 |
|---|---|---|
| موتور | PostCSS + جاوااسکریپت | Rust (Oxide) |
| تنظیمات | tailwind.config.js | CSS @theme |
| پلاگین | require در config | @plugin در CSS |
| کلاس‌های سفارشی | @layer utilities | @utility |
| Container Queries | پلاگین جدا | داخلی (@container) |
| corePlugins | بود | حذف شد |
| theme() | تابع جاوااسکریپت | از CSS variable استفاده کن |
| نام کلاس‌های utility | — | تقریبا دست‌نخورده |
تله‌هایی که سر راه می‌بینی
۱. @layer utilities دیگر کار نمی‌کند. کلاس سفارشی خودت را قبلا داخل @layer utilities می‌نوشتی که با hover: و lg: هماهنگ شود. در v4 این را @utility صدا می‌زنیم:
۲. theme() قدیمی را کنار بگذار. به‌جای theme("colors.primary") از var(--color-primary) استفاده کن.
۳. پلاگین‌های شخص ثالث، نه تو. تجربه‌ی پروژه‌های واقعی نشان می‌دهد ریسک مهاجرت بیشتر در پلاگین‌هاست تا تمپلیت. قبل از هر کاری لیست پلاگین‌هایت را چک کن که نسخه‌ی سازگار با v4 دارند یا نه — اگر پلاگین قدیمی باشد، بقیه‌ی کار را خراب می‌کند.
۴. ساختار رنگ‌های تودرتو. اگر در config قبلی colors.brand.light داشتی، بعد از مهاجرت باید اسم را صاف کنی: --color-brand-light.
چک‌لیست مهاجرت
- [ ] خط پایه ثبت شده: قبل از هر تغییری
npm run buildبزن و سایز CSS و زمان بیلد را یادداشت کن - [ ] مسیر مهاجرت انتخاب شده:
npx @tailwindcss/upgradeروی یک برنچ جدید، یا همان ۶ قدم دستی - [ ]
@tailwind base/components/utilitiesبا یک خط@import "tailwindcss";جایگزین شده - [ ] همه‌ی مقادیر theme از
tailwind.config.jsبه بلوک@themeبه‌صورت CSS variable منتقل شده‌اند - [ ] پلاگین‌ها با
@pluginصدا زده شده‌اند و وجود نسخه‌ی سازگار با v4 برای هرکدام تأیید شده - [ ] در صورت وجود،
postcss-importوautoprefixerاز کانفیگ PostCSS حذف شده‌اند - [ ] پشتیبانی مرورگر در برابر Safari 16.4+، Chrome 111+ و Firefox 128+ بررسی شده
- [ ] خروجی بیلد در مرورگر بازبینی شده، با دقت به مقیاس‌های تغییرنام‌داده‌ی
shadow-*،rounded-*وblur-*
سوالات پرتکرار
Q: کلاس‌های فعلی‌ام (flex، text-sm، bg-red-500) عوض می‌شوند؟
نه. نام utilityها تقریبا ثابت مانده؛ بیشتر تمپلیت‌های v3 بدون هیچ ویرایش HTML زیر v4 کامپایل می‌شوند. کار واقعی روی config و پلاگین‌هاست. استثنا utilityهای تغییرنام‌داده‌ی مقیاس‌ها هستند: shadow-sm شده shadow-xs و shadow شده shadow-sm، و همین الگو برای rounded-* و blur-* هم تکرار می‌شود.
Q: می‌توانم v3 و v4 را با هم داشته باشم؟
نه منطقی نیست. v4 یک breaking change عمدی است؛ بهتر است یک‌جا مهاجرت کنی. برای پروژه‌ی بزرگ، مهاجرت تدریجی با @source ممکن است ولی دردسرش بیشتر است.
Q: آیا tailwind.config.js کاملا حذف شده؟
برای سازگاری backwards هنوز پشتیبانی می‌شود، ولی در v4 دیگر به‌صورت خودکار پیدا نمی‌شود و باید صریح با @config "../../tailwind.config.js" بارگذاری‌اش کنی. مسیر توصیه‌شده همان CSS-first است، با توکن‌های طراحی به‌صورت CSS variable.
دو نکته‌ی دیگر که در ادامه‌ی همین بحث به کارت می‌آید:
- چرا حجم CSS خروجی کم می‌شود: موتور جدید overhead نسخه‌ی قبل را حذف می‌کند و چون theme به‌صورت CSS variable تولید می‌شود، تکرارها از بین می‌روند.
- Next.js: در Next.js 15+ از
@tailwindcss/postcssاستفاده کن:@import "tailwindcss"در فایل CSS اصلی و پلاگین PostCSS درpostcss.config.mjs.
جمع‌بندی
مهاجرت به Tailwind v4 یعنی پذیرفتن یک جابه‌جایی بزرگ در فلسفه: تنظیمات از جاوااسکریپت به CSS منتقل شد و موتور از جاوااسکریپت به Rust عوض شد. نتیجه‌ی عملی برای تو: بیلد سریع‌تر، HMR آنی‌تر و CSS سبک‌تر. با این ۶ قدم و چک‌لیست بالا، پروژه‌ات را در یک جلسه‌ی کاری کوچک جابه‌جا می‌کنی — فقط حواست به پلاگین‌ها باشد.