Tailwind CSS v4: دليل الترحيل والميزات الجديدة

يعد Tailwind CSS v4 أهم عملية إعادة كتابة منذ إطلاق الإطار. اختفى ملف تكوين JavaScript، وتم استبداله بتكوين CSS-first باستخدام خصائص مخصصة. لم تتغير فئة واجهة برمجة التطبيقات (API) إلى حد كبير، ولكن الأجزاء الداخلية جديدة تمامًا: محرك قائم على Rust (oxide)، ودعم من الدرجة الأولى لنطاق ألوان P3، واستعلامات الحاوية الأصلية، وخط أنابيب البناء الذي يتكامل مباشرة مع CSS بدلاً من المكونات الإضافية لـ PostCSS.

يرشدك هذا الدليل إلى ما تغير، ولماذا تغير، وكيفية ترحيل تطبيق إنتاج حقيقي من Tailwind v3 إلى v4. سنغطي التغييرات العاجلة التي ستؤدي إلى إعاقتك والميزات الجديدة التي تستحق اعتمادها على الفور.

الوجبات الرئيسية

• تم إهمال tailwind.config.js - ينتقل التكوين إلى CSS باستخدام التوجيه @theme
• تم تغيير الاستيراد من @tailwind base/components/utilities إلى @import "tailwindcss" واحد
• تستخدم الألوان المخصصة الآن خصائص CSS المخصصة ضمن مساحة الاسم --color-*
• يكون تكوين content تلقائيًا — يقوم Tailwind v4 بفحص الملفات تلقائيًا عبر الكرة الأرضية
• أصبحت استعلامات الحاوية مدمجة الآن مع المتغيرات @container و@sm: و@lg:
• دعم التدرج اللوني P3 عبر مساحة الألوان oklch() لجميع الألوان المدمجة
• @apply لا يزال يعمل ولكنه أقل أهمية مع خصائص CSS المخصصة
• تم استبدال محرك JIT بأكسيد (الصدأ) - وهو تجميع أسرع بشكل كبير

---

ما الذي تغير ولماذا

استخدم Tailwind v3 PostCSS كخط أنابيب للمعالجة، وملف تكوين JavaScript، وفئات الأدوات المساعدة التي تم إنشاؤها عبر محرك JIT المكتوب بلغة JavaScript. لقد نجح هذا بشكل جيد ولكن كان له قيود:

• يتطلب التكوين JavaScript، مما يجعل الوصول إليه غير ممكن من خلال أدوات CSS فقط
• يجب تعيين الخصائص المخصصة بشكل منفصل عن تكوين Tailwind
• استعلامات الحاوية تتطلب مكونًا إضافيًا
• نظام الألوان لا يدعم سلسلة P3

يعالج Tailwind v4 كل هذه الأمور عن طريق نقل التكوين إلى CSS نفسه، باستخدام نظام خصائص CSS المخصص الأصلي للمتصفح، وإعادة كتابة المحرك في Rust من أجل إنشاءات أسرع بمعدل 5 إلى 10 مرات.

---

التثبيت

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

يتكامل البرنامج المساعد @tailwindcss/vite مباشرة مع Vite. بالنسبة إلى Next.js (الذي يستخدم PostCSS داخليًا)، استخدم @tailwindcss/postcss.

---

التكوين الأول لـ CSS

هذا هو أكبر تغيير مفاهيمي. يصبح globals.css الخاص بك هو المصدر الحقيقي لتكوين Tailwind:

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

يمكن حذف tailwind.config.js الخاص بك (أو الاحتفاظ به في الوقت الحالي — يدعم الإصدار 4 كليهما أثناء الترحيل).

---

كشف المحتوى

يكتشف Tailwind v4 ملفات القالب تلقائيًا. لقد اختفى تكوين content الذي حافظت عليه بدقة في الإصدار الثالث:

// v3 tailwind.config.js — you needed this
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

في الإصدار الرابع، يقوم Tailwind بفحص مشروعك تلقائيًا باستخدام الإعدادات الافتراضية المعقولة. إذا كانت لديك ملفات في مواقع غير معتادة، فيمكنك تضمينها بشكل صريح:

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

---

تحديث تكوين PostCSS

بالنسبة لمشاريع Next.js (وأي إعداد يستند إلى PostCSS)، قم بتحديث تكوين PostCSS الخاص بك:

// Before: postcss.config.js with v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

يتم تضمين autoprefixer في @tailwindcss/postcss بشكل افتراضي. قم بإزالة تبعية autoprefixer المنفصلة.

---

نظام الألوان: OKLCH

يستخدم Tailwind v4 OKLCH للوحة الألوان المدمجة فيه. OKLCH عبارة عن مساحة لونية موحدة إدراكيًا - يبدو ضبط الإضاءة في الواقع بمثابة خطوات متساوية للعين البشرية، على عكس HSL.

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

بالنسبة لشاشات العرض ذات النطاق الأوسع (معظم الهواتف وأجهزة Mac الحديثة)، يتيح OKLCH الألوان التي لا يمكن لـ sRGB تمثيلها ببساطة. يتم تحويل قيم oklch() تلقائيًا إلى rgb() لشاشات العرض التي لا تدعم P3.

---

استعلامات الحاوية — مدمجة

أصبحت استعلامات الحاوية الآن من الدرجة الأولى في الإصدار 4. لا حاجة إلى البرنامج المساعد:

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

يؤدي ذلك إلى تمكين الاستجابة على مستوى المكونات - يمكن أن تحتوي بطاقة الشريط الجانبي وبطاقة العرض الكامل على تخطيطات مختلفة دون الحاجة إلى CSS منفصل.

تتيح لك الحاويات المُسماة استهداف أسلاف محددين:

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

---

تكامل خصائص CSS المخصصة

يمكن الوصول إلى الخصائص المخصصة المحددة في @theme في كل مكان — CSS، وJavaScript، وأدوات التصميم التي تقرأ متغيرات CSS:

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

يستبدل هذا نمط الحفاظ على القيم المتوازية في tailwind.config.js وملف tokens.ts - يوجد الآن مصدر واحد للحقيقة في CSS.

---

كسر التغييرات

1. تغييرات واجهة برمجة التطبيقات الإضافية

المكونات الإضافية v3 التي تستخدم addBase، addComponents، addUtilities غير متوافقة مع الإصدار 4. أعد كتابتها بتنسيق CSS باستخدام نظام الطبقات الجديد:

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium;
  }
}

2. @apply مع فئات مخصصة

@apply مع الفئات غير Tailwind مقيد بشكل أكبر في الإصدار 4. استخدم @apply فقط مع فئات المرافق الفعلية:

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend اختفى

لم يعد التكوين في JS هو المسار الأساسي. استخدم @theme في CSS. إذا كان لديك كليهما، فإن تكوين CSS له الأولوية.

4. تسمية لوحة الألوان الافتراضية

تم تغيير بعض أسماء الألوان في الإصدار 4. قم بتشغيل codemod الرسمي للقبض عليهم:

npx @tailwindcss/upgrade@next --config tailwind.config.js

---

استراتيجية الهجرة

بالنسبة لتطبيق إنتاج كبير، قم بالترحيل بشكل متزايد:

المرحلة الأولى: تثبيت التحديث

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

تحديث postcss.config.mjs:

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

تحديث globals.css:

/* Replace the three @tailwind directives */
@import "tailwindcss";

المرحلة الثانية: تشغيل الكود

npx @tailwindcss/upgrade@next

يؤدي هذا إلى أتمتة معظم عمليات الترحيل: تحديث أسماء الألوان، وتحويل التكوين إلى CSS، ووضع علامة على المشكلات التي تحتاج إلى اهتمام يدوي.

المرحلة 3: نقل التكوين إلى CSS

خذ قيم السمة tailwind.config.js وانقلها إلى @theme في CSS الخاص بك. احذف ملف التكوين بعد التحقق.

المرحلة الرابعة: اعتماد ميزات جديدة

استبدل نقاط التوقف المستجيبة المستندة إلى إطار العرض باستعلامات الحاوية حيثما كان ذلك مناسبًا. استخدم OKLCH للألوان المخصصة للحصول على دعم التدرج اللوني P3.

---

تحسينات الأداء

يوفر محرك الأكسيد (Rust) الخاص بـ Tailwind v4 تصميمات أسرع بشكل ملحوظ:

بالنسبة للتطبيقات الكبيرة، يُترجم هذا إلى HMR أسرع بشكل ملحوظ في التطوير وأوقات إنشاء CI أقصر بشكل ملحوظ.

---

مثال للهجرة في العالم الحقيقي

فيما يلي عرض عملي قبل/بعد للتكوين الأساسي لنظام التصميم:

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

يعد تكوين CSS الأصلي أكثر إيجازًا ويزيل تبعية node_modules لقراءة التكوين.

---

الأسئلة المتداولة

هل أحتاج إلى حذف tailwind.config.js فورًا؟

لا — يدعم Tailwind v4 كلاً من تكوين JS وتكوين CSS في وقت واحد أثناء الترحيل. لا يزال تكوين JS يعمل، لكن ميزات مثل @theme في CSS متاحة فقط بدونه. الترحيل تدريجيًا: قم أولاً بإنشاء التطبيق باستخدام الإصدار 4، ثم انقل التكوين تدريجيًا إلى CSS، ثم احذف تكوين JS عندما تكون واثقًا.

هل ستظل فئات Tailwind v3 الحالية تعمل في الإصدار 4؟

الغالبية العظمى من فئات المرافق لم تتغير. تم تحديث بعض أسماء الألوان (الرمادي → محايد في بعض السياقات)، وتمت إزالة بعض الأدوات المساعدة المهملة. قم بتشغيل npx @tailwindcss/upgrade@next لاكتشاف معظم المشكلات تلقائيًا. توجد حالات عدم التوافق الرئيسية في المكونات الإضافية وتكوين السمات المخصصة، وليس في كيفية استخدام الفئات في HTML/JSX.

هل OKLCH مدعوم في جميع المتصفحات؟

يتم دعم OKLCH في جميع المتصفحات الحديثة (Chrome 111+، Firefox 113+، Safari 15.4+). يقوم Tailwind v4 بإنشاء إجراءات احتياطية للمتصفحات الأقدم عند الحاجة. بالنسبة إلى التدرج اللوني P3 (الألوان الموسعة)، يتطلب الدعم كلاً من شاشة عرض ذات نطاق واسع ومتصفح داعم — يقوم Tailwind بإنشاء rgb() احتياطية لشاشات ذات نطاق أضيق.

كيف يمكنني استخدام Tailwind v4 مع shadcn/ui؟

shadcn/ui 2.0+ يدعم Tailwind v4. قم بتحديث components.json الخاص بك لاستخدام تنسيق متغيرات v4 CSS. تستخدم مكتبة المكونات خصائص CSS المخصصة للتخصيص، والتي يتم تعيينها بشكل طبيعي لنظام @theme الخاص بـ Tailwind v4. قم بتشغيل npx shadcn@latest init في مشروع موجود للحصول على التكوين المتوافق مع الإصدار 4.

هل هناك أنواع TypeScript للتكوين الجديد؟

تكوين Tailwind v4 هو CSS، لذلك لا توجد أنواع TypeScript للتكوين نفسه. يأتي دعم IDE من خدمات لغة CSS التي تفهم الخصائص المخصصة. للوصول إلى قيم السمات في TypeScript (للمخططات والرسوم المتحركة وما إلى ذلك)، استخدم getComputedStyle لقراءة خصائص CSS المخصصة في وقت التشغيل، أو قم بإنشاء ملف الرموز المميزة من CSS الخاص بك كجزء من الإصدار الخاص بك.

---

الخطوات التالية

يعد Tailwind CSS v4 ترقية مهمة تستحق اعتمادها للمشروعات الجديدة والتخطيط للمشاريع الحالية. تعمل مجموعة الواجهة الأمامية لـ ECOSIRE على تشغيل Tailwind CSS v4.1 في الإنتاج عبر تطبيق Next.js 16 المكون من 249 صفحة مع نظام تصميم شامل.

هل تحتاج إلى مساعدة بشأن ترحيل Tailwind v4 أو تريد إنشاء نظام تصميم من الألف إلى الياء؟ استكشف خدماتنا الهندسية للواجهة الأمامية لمعرفة كيف يمكننا مساعدتك.