موجّه إرشادي صارم لبناء مشاريع Astro v6 بأقل JavaScript، مع الالتزام بمعمارية الجزر، والتهيئة التفاعلية المتدرجة، ومنطق الخادم أولًا.
View original English source# قواعد معمارية 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 بقدر الحاجة»