إعداد Astro وجزر React

يتم إنشاء مشروع Astro باستخدام npx create astro@latest، الذي يشغّل معالجًا تفاعليًا لاختيار قالب وإعدادات TypeScript ومدير الحزم. يدعم Astro عدة قوالب ابتدائية، منها قالب فارغ وقالب للمدونات وقوالب للتوثيق.

تضيف تكاملات Astro دعم أطر العمل إلى المشروع. يؤدي تشغيل npx astro add react إلى تثبيت @astrojs/react وreact وreact-dom تلقائيًا، وتحديث astro.config.mjs لتضمين تكامل React. يستغرق الإعداد بأكمله أمرًا واحدًا.

ملف .astro هو تنسيق المكوّنات في Astro. ويتكوّن من قسم frontmatter (JavaScript بين سياجي ---) وقسم للقالب. يُخرج ملف Astro، افتراضيًا، HTML ثابتًا — ولا يُرسل أي JavaScript إلى المتصفح ما لم تُضف توجيهًا للعميل صراحةً.

يستخدم استيراد مكوّن React إلى ملف Astro الصيغة القياسية لوحدات ES: import Counter from './Counter.jsx'. من دون توجيه للعميل، يعرض Astro مكوّن React من جانب الخادم بصيغة HTML ثابتة، ثم يرسل HTML هذا إلى المتصفح — من دون إرسال أي JavaScript للمكوّن.

تؤدي إضافة client:visible إلى وسم المكوّن في قالب Astro إلى تحويله إلى جزيرة: <Counter client:visible />. يرسل Astro الآن JavaScript الخاص بـ Counter، ويرطّبه عند ظهوره أثناء التمرير، ويجعله تفاعليًا. ومن دون التوجيه، يكون HTML ثابتًا.

تُكتب مكوّنات React المستخدمة كجزر Astro باستخدام React القياسي — فهي تستخدم hooks والحالة والتأثيرات وأي مكتبة من مكتبات React. ولا توجد واجهة API خاصة بـ Astro داخل مكوّن React نفسه. يُحدَّد حدّ الجزيرة في قالب Astro، وليس داخل رمز المكوّن.

كل نسخة من الجزيرة هي شجرة React مستقلة. ولا تشترك جزيرتا Counter في الصفحة نفسها في الحالة. إذا احتجتم إلى حالة مشتركة، فلديكم ثلاثة خيارات: دمجهما في جزيرة واحدة، أو استخدام معاملات البحث في URL للحالة القابلة للتسلسل، أو استخدام مكتبة للحالة المشتركة مثل nanostores.

توفر مكتبة @nanostores/react ذرات خفيفة يمكن لأي جزيرة الاشتراك فيها. تكتب إحدى الجزر إلى ذرة في nano store، بينما تقرؤها جزيرة أخرى. وبما أن nano stores مستقلة عن إطار العمل، فإن هذا النمط يعمل أيضًا بين جزر React وVue في الصفحة نفسها.

توفر مجموعات محتوى Astro طريقة آمنة من ناحية الأنواع لإدارة ملفات Markdown وMDX. عرّفوا مخطط مجموعة باستخدام Zod، وضعوا ملفات Markdown في src/content/، وسيُنشئ Astro دوال استعلام مكتوبة بالكامل. وهذا هو النمط القياسي لمنشورات المدونات والتوثيق وصفحات المنتجات.

يؤدي تشغيل astro build إلى إنشاء مجلد dist/ يحتوي على ملفات HTML ثابتة. ولكل صفحة، يُخرج Astro ملف HTML يتضمن المحتوى المعروض من جانب الخادم وحِزم JavaScript اللازمة فقط للجزر الموجودة في تلك الصفحة. أما الصفحات التي لا تحتوي على جزر، فلا تُخرج أي JavaScript.

يمكن نشر الناتج الثابت على أي CDN مثل Netlify وVercel وCloudflare Pages من دون خادم. ولتلبية احتياجات العرض من جانب الخادم، مثل المسارات الديناميكية ونقاط نهاية API، يدعم Astro محوّلات SSR لـ Node.js وVercel Edge وCloudflare Workers وDeno. وتعمل الجزر بالطريقة نفسها في كلا الوضعين.

أعدّوا Astro مع React باستخدام npx astro add react. تكون ملفات Astro ثابتة افتراضيًا؛ وتؤدي إضافة توجيه client: إلى وسم مكوّن React إلى تحويله إلى جزيرة مُرطّبة. مكوّنات React هي React قياسي ولا تستخدم واجهات API خاصة بـ Astro. وتكون الحالة معزولة لكل جزيرة، بينما تتيح nanostores التواصل بين الجزر. ويُخرج البناء HTML ثابتًا مع JavaScript الخاص بالجزر اللازمة فقط.