React على Cloudflare Workers باستخدام Hono

Hono هو إطار عمل ويب خفيف وسريع للغاية، صُمّم للعمل على بيئات تشغيل Edge، بما في ذلك Cloudflare Workers وDeno Deploy وBun وNode.js. وتستلهم واجهته البرمجية تصميمها من Express، لكنها بُنيت من الأساس وفق معايير الويب، مثل Fetch API وRequest/Response، مما يجعلها ملائمة طبيعيًا لبيئات Edge.

إنشاء مشروع Hono جديد لـ Cloudflare Workers أمر مباشر: إذ يطلب منك npm create hono@latest اختيار قالب، ثم اختيار "cloudflare-workers"، وينشئ مشروعًا مهيّأ مسبقًا باستخدام wrangler، وهي واجهة Cloudflare لسطر الأوامر، وتبعية Hono.

لتصيير React على الخادم داخل Worker من Hono، ثبّت react وreact-dom و@types/react، ثم استورد renderToReadableStream من react-dom/server. وهذه الدالة جزء من واجهة البث في React 18، وقد صُممت للبيئات التي تدعم Web Streams API، وهو ما تفعله Cloudflare Workers.

يستدعي معالج مسار SSR المعتاد renderToReadableStream مع مكوّن React الجذر، وينتظر الدفق، ثم يستخدم c.body(stream, { headers: { "Content-Type": "text/html" } }) أو c.html(htmlString) لإرسال الاستجابة. وينتج الدفق أجزاءً من HTML يمكن للمتصفح تصييرها تدريجيًا.

تعيد renderToReadableStream وعدًا Promise يُحل إلى ReadableStream من أجزاء HTML. ويتوافق ReadableStream هذا مع Web Streams API، ويمكن تمريره مباشرةً بوصفه جسم كائن Response، مما يجعله ملائمًا تمامًا لمعالج fetch في Cloudflare Workers.

ينتج دفق React لغة HTML لشجرة المكوّنات، لكنه لا ينتج المستند المحيط بها. لذلك يجب إدخال الدفق في هيكل HTML: سلسلة تحتوي على doctype، وعنصر head الذي يتضمن وسوم meta ورابط CSS، ووسم body الافتتاحي، ثم دفق React، ثم وسمَي body وhtml الختاميين.

يحتاج حزمة React العميلة التي أنشأها Vite إلى أن تُقدَّم إلى جانب Worker. وتتولى Cloudflare Pages أو ميزة Workers Assets ذلك؛ إذ يوجّه c.env.ASSETS.fetch(request) طلبات الأصول، مثل JS وCSS والصور، إلى الملفات الثابتة التي رُفعت مع عملية نشر Worker.

يصدّر ملف إدخال Worker كائنًا افتراضيًا يتضمن معالج fetch: export default { fetch: app.fetch }. وتكون دالة app.fetch في Hono متوافقة أصلًا مع معالج fetch؛ فهي تتلقى Request وتعيد Response، ولذلك تتصل مباشرةً ببيئة تشغيل Workers.

يشغّل wrangler dev خادم تطوير محليًا يحاكي بيئة تشغيل Cloudflare Workers على جهازك. ويراقب تغييرات الملفات ويعيد التحميل تلقائيًا، موفرًا دورة تطوير محلية سريعة قبل النشر إلى الإنتاج.

يجمع wrangler deploy شيفرة Worker الخاصة بك ويرفعها إلى شبكة Cloudflare، فتصبح متاحة في أكثر من 300 موقع Edge خلال ثوانٍ. ويحدد ملف الإعداد wrangler.toml معرّف حسابك واسم Worker وأي ربط بمساحة أسماء KV أو قاعدة بيانات D1.

لإتاحة التفاعل من جهة العميل، مرّر bootstrapScripts: ['/assets/client.js'] إلى renderToReadableStream. وستُدخل React وسم script في HTML لتحميل حزمة العميل واستدعاء hydrateRoot على DOM المصيّر من الخادم، مما يجعل الصفحة تفاعلية بعد تحميل JavaScript.

ماذا تعيد renderToReadableStream؟

يوفر Hono إطار HTTP خفيفًا ومصممًا أصلًا لـ Edge، ويتكامل بسلاسة مع renderToReadableStream في React. وتصدّر نقطة إدخال Worker app.fetch مباشرةً إلى بيئة تشغيل Workers، بينما تُقدَّم الأصول الثابتة عبر عمليات ربط ASSETS، ويتولى wrangler التطوير المحلي والنشر إلى الإنتاج. وتربط bootstrapScripts لغة HTML المتدفقة بحزمة الترطيب من جهة العميل.