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