قواعد Astro.js المعمارية

# قواعد معمارية Astro v6 (الوضع الصارم)

## 1. الفلسفة الأساسية

- التزم بمبدأ Astro: «HTML أولًا / بدون JavaScript افتراضيًا»:
  - كل شيء يُنتج كـ HTML ثابت ما لم تكن التفاعلية مطلوبة صراحة.
  - JavaScript له تكلفة → لا تضِفه إلا عندما يضيف قيمة حقيقية للمستخدم.

- فكّر دائمًا وفق «معمارية الجزر»:
  - الصفحة HTML ثابت
  - الأجزاء التفاعلية جزر مستقلة
  - لا تتعامل مع الصفحة كاملة كأنها تطبيق واحد

- قبل كتابة أي JavaScript، اسأل دائمًا:
  «هل يمكن حل هذا باستخدام HTML + CSS أو منطق جهة الخادم؟»

---

## 2. نموذج المكونات

- استخدم مكونات `.astro` من أجل:
  - التخطيط العام
  - التركيب وتجميع المكونات
  - واجهات المستخدم الثابتة
  - جلب البيانات
  - منطق جهة الخادم داخل frontmatter

- مكونات `.astro`:
  - تعمل وقت البناء أو على جهة الخادم
  - لا ترسل JavaScript للمتصفح افتراضيًا
  - يجب أن تبقى غير مرتبطة بإطار عمل معيّن

- يُمنع تمامًا استخدام Hooks الخاصة بـ React/Vue/Svelte داخل ملفات `.astro`

---

## 3. الجزر (المكونات التفاعلية)

- استخدم مكونات أطر العمل مثل React أو Vue أو Svelte فقط عند الحاجة للتفاعلية.

- تعامل مع كل مكون تفاعلي كجزيرة مستقلة:
  - مستقلة
  - مكتفية بذاتها
  - محدودة النطاق وواضحة

- ممنوع:
  - تفعيل Hydration لصفحات أو layouts كاملة
  - تغليف أشجار مكونات كبيرة داخل جزيرة واحدة
  - إنشاء عدد كبير من الجزر الصغيرة داخل الحلقات بدون حاجة فعلية

- الأفضل:
  - عرض القوائم بشكل ثابت
  - تفعيل Hydration لأصغر وحدة تفاعلية ممكنة فقط

---

## 4. استراتيجية Hydration (مهم جدًا)

- عرّف Hydration دائمًا بشكل صريح باستخدام توجيهات `client:*`.

- اختر أقل أولوية ممكنة:

  - `client:load`
    → فقط للتفاعلية الحرجة في الجزء الظاهر أول الصفحة

  - `client:idle`
    → لعناصر الواجهة الثانوية بعد تحميل الصفحة

  - `client:visible`
    → للمكونات الثقيلة أو الموجودة أسفل الجزء المرئي

  - `client:media`
    → للواجهات المتجاوبة أو المشروطة

  - `client:only`
    → فقط عندما يتعطل SSR بسبب `window` أو `localStorage` أو ما شابه

- القاعدة الافتراضية:
  ❌ لا تعتمد `client:load` كخيار افتراضي
  ✅ فضّل `client:visible` أو `client:idle`

- تعامل مع Hydration كميزانية أداء:
  - كل جزيرة تضيف JavaScript
  - أبقِ إجمالي JavaScript عند الحد الأدنى

📌 لا يفعّل Astro الـ Hydration للمكونات إلا إذا طُلب ذلك صراحة عبر `client:*` :contentReference[oaicite:0]{index=0}  

---

## 5. منطق الخادم مقابل منطق العميل

- فضّل منطق جهة الخادم داخل frontmatter في ملفات `.astro` من أجل:
  - جلب البيانات
  - التحويلات والمعالجات
  - التصفية / الترتيب
  - القيم المشتقة

- استخدم الحالة على جهة العميل فقط عندما:
  - يتطلب تفاعل المستخدم ذلك
  - تكون التحديثات اللحظية مطلوبة

- تجنب:
  - تكرار المنطق على جهة العميل
  - نقل منطق الخادم إلى الجزر التفاعلية

---

## 6. إدارة الحالة

- تجنب الحالة على جهة العميل إلا عند الضرورة الفعلية.

- إذا احتجت إليها:
  - احصر الحالة داخل الجزيرة نفسها
  - لا تنشئ حالة عامة للتطبيق إلا إذا كانت مطلوبة فعلًا

- للحالة المشتركة بين الجزر:
  - استخدم مخازن مشتركة خفيفة مثل Nano Stores
  - تجنب أنظمة إدارة الحالة العامة الثقيلة كخيار افتراضي

---

## 7. قيود الأداء (قواعد صارمة)

- قلّل JavaScript المرسل للمتصفح قدر الإمكان:
  - يحمّل Astro JavaScript فقط للمكونات التي تم تفعيل Hydration لها :contentReference[oaicite:1]{index=1}  

- فضّل:
  - التصيير الثابت
  - Hydration جزئي
  - Hydration مؤجل

- تجنب:
  - تفعيل Hydration لقوائم كبيرة
  - تكرار الجزر داخل الحلقات
  - الإفراط في استخدام `client:load`

- كل جزيرة:
  - لها bundle خاص بها
  - يتم تحميلها بشكل مستقل
  - يجب أن تبقى صغيرة ومركزة :contentReference[oaicite:2]{index=2}  

---

## 8. هيكلة الملفات والمشروع

- `/pages`
  - نقاط الدخول (SSG/SSR)
  - بدون منطق على جهة العميل

- `/components`
  - واجهات مشتركة
  - الجزر التفاعلية تكون هنا

- `/layouts`
  - أغلفة ثابتة فقط

- `/content`
  - بيانات Markdown / CMS

- أبقِ ملفات `.astro` مركزة على التركيب، لا على السلوك التفاعلي

---

## 9. أنماط ممنوعة (محظورة تمامًا)

- ❌ استخدام Hooks داخل `.astro`
- ❌ تحويل Astro إلى معمارية SPA
- ❌ تفعيل Hydration للـ layout أو الصفحة بالكامل
- ❌ استخدام `client:load` في كل مكان
- ❌ تحويل عناصر القوائم إلى مكونات مفعّل لها Hydration
- ❌ استخدام JavaScript على جهة العميل لحل مسائل ثابتة
- ❌ استبدال منطق الخادم بمنطق جهة العميل

---

## 10. الأنماط المفضلة

- ✅ التصيير الثابت أولًا
- ✅ جزر محدودة، معزولة، وواضحة النطاق
- ✅ Hydration مؤجل باستخدام `visible` أو `idle`
- ✅ الحساب والمعالجة على جهة الخادم
- ✅ HTML + CSS قبل JavaScript
- ✅ التحسين التدريجي

---

## 11. إطار اتخاذ القرار (مهم جدًا)

لكل ميزة:

1. هل يمكن تنفيذها كـ HTML ثابت؟
   → نعم → استخدم `.astro`

2. هل تتطلب تفاعلًا؟
   → لا → أبقِها ثابتة

3. هل تتطلب JavaScript؟
   → نعم → أنشئ جزيرة

4. متى يجب تحميلها؟
   → اختر أقل أولوية ممكنة من `client:*`

---

## 12. النموذج الذهني (غير قابل للتفاوض)

- Astro ليس:
  - Next.js
  - إطار SPA
  - نظام مبني حول React أولًا

- Astro هو:
  - محرك تصيير يبدأ بالثابت
  - نظام Hydration جزئي
  - معمارية تعطي الأداء الأولوية

- فكّر بهذه الطريقة:
  ❌ «نبني تطبيق كامل»
  ✅ «نرسل HTML ونضيف JavaScript بقدر الحاجة»