مهاجرت به Tailwind CSS v4: موتور Oxide، تنظیمات CSS-First و بیلدی که ۸ برابر سریع‌تر شد

چکیده (TL;DR): Tailwind v4 از یه موتور جدید به اسم Oxide (نوشته‌شده با Rust) استفاده می‌کنه که بیلد رو تا ۸ برابر و HMR رو تا ۹۶٪ سریع‌تر کرده. مهم‌ترین تغییر برای تو: فایل tailwind.config.js دیگه نیست — همه‌ی تنظیمات می‌ره توی CSS با بلوک @theme. خود کلاس‌های utility تقریبا دست‌نخورده موندن، پس مهاجرت بیشتر درباره‌ی «پلاگین‌ها و config» هست تا «HTML». توی ۱۰ دقیقه تموم می‌شه.

وقتی Tailwind v4 آپدیت شد، بیشتر ما فکر کردیم «فقط یه نسخه‌ی جدید دیگه». ولی این مهاجرت با بقیه فرق داره: فلسفه‌ی پیکربندی کاملا عوض شده. اگه توی یه پروژه‌ی قدیمی با v3 مونده باشی، این مطلب دقیقا برای توئه — با استعاره و کد، نه با اصطلاحات قلمبه‌سلمبه.

چرا اصلا آپدیت کنیم؟ — جدول قبل و بعد

Oxide فقط یه «کمی سریع‌تر» نیست؛ یه مرتبهی بزرگی فرق داره. اعداد واقعی از پروژه‌های مهاجرت‌کرده:

| معیار | v3 | v4 (Oxide) | بهبود | |---|---|---|---| | بیلد سرد (cold build) | ~12.3 ثانیه | ~1.8 ثانیه | ~۸ برابر سریع‌تر | | استارت سرور توسعه | ~4.2 ثانیه | ~0.8 ثانیه | ~۸۱٪ | | آپدیت HMR | ~340 میلی‌ثانیه | ~12 میلی‌ثانیه | ~۹۶٪ | | حجم CSS نهایی | ~48KB | ~31KB | ~۳۵٪ کوچیک‌تر | | مصرف حافظه | ~180MB | ~45MB | ~۷۵٪ کمتر |

استعاره‌ش ساده‌ست: v3 هر بار یه کارگاه کامل رو از نو راه می‌نداخت که «کدوم کلاس‌ها استفاده شدن؟» رو بشمره؛ v4 با موتور Rust این شمارش رو در حد چند میلی‌ثانیه انجام می‌ده. نتیجه: توی پروژه‌ی بزرگ، F5 زدن و منتظر موندن دیگه تموم می‌شه.

نقشه‌ی راه: ۶ قدم مهاجرت

قدم ۱ — وابستگی‌ها رو آپدیت کن

اگه از @tailwindcss/vite استفاده می‌کنی، پلاگین قدیمی رو از vite.config.ts بردار و این رو بذار:

قدم ۲ — دستورات @tailwind رو عوض کن

قدم ۳ — config رو ببر توی CSS (مهم‌ترین قدم!)

تو v3 رنگ دلخواهت توی یه آبجکت جاوااسکریپت بود:

تو v4 این می‌شه CSS واقعی — با بلوک @theme:

دو نکته‌ی مهم:

1. اسم‌ها صاف شدن: colors.brand.light قبلی حالا --color-brand-light است، نه --color-brand.light.
2. این‌ها 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.

سوالات پرتکرار (FAQ)

سوال: کلاس‌های فعلی‌ام (flex، text-sm، bg-red-500) عوض می‌شوند؟ جواب: نه. نام utilityها تقریبا ثابت مانده؛ بیشتر تمپلیت‌های v3 بدون هیچ ویرایش HTML زیر v4 کامپایل می‌شوند. کار واقعی روی config و پلاگین‌هاست.

سوال: می‌توانم v3 و v4 را با هم داشته باشم؟ جواب: نه منطقی نیست. v4 یک breaking change عمدی است؛ بهتر است یک‌جا مهاجرت کنی. برای پروژه‌ی بزرگ، مهاجرت تدریجی با @source و جدا کردن استایل‌ها ممکن است ولی دردسرش بیشتر است.

سوال: آیا tailwind.config.js کاملا حذف شده؟ جواب: برای موارد پیشرفته هنوز می‌توانی از آن استفاده کنی، ولی مسیر اصلی و توصیه‌شده CSS-first است؛ config در v4 دیگر مرجع طراحی نیست.

سوال: 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 سبک‌تر. با این ۶ قدم و چک‌لیست بالا، پروژه‌ات را در یک جلسه‌ی کاری کوچک جابه‌جا می‌کنی — فقط حواست به پلاگین‌ها باشد.