React sur Cloudflare Workers avec Hono

Hono est un cadriciel Web léger et extrêmement rapide, conçu pour s'exécuter dans des environnements en périphérie comme Cloudflare Workers, Deno Deploy, Bun et Node.js. Son interface s'inspire d'Express, mais a été conçue dès le départ pour les normes du Web (interface Fetch, Request/Response), ce qui en fait un choix naturel pour les environnements en périphérie.

La création de la structure d'un nouveau projet Hono pour Cloudflare Workers est simple : npm create hono@latest vous invite à choisir un modèle, à sélectionner "cloudflare-workers", puis crée un projet préconfiguré avec wrangler (l'interface CLI de Cloudflare) et la dépendance Hono.

Pour effectuer le rendu côté serveur de React dans un Worker Hono, installez react, react-dom et @types/react, puis importez renderToReadableStream depuis react-dom/server. Cette fonction fait partie de l'interface de diffusion en flux de React 18 et est conçue pour les environnements qui prennent en charge l'interface Web Streams, ce qui est le cas de Cloudflare Workers.

Un gestionnaire de route SSR typique appelle renderToReadableStream avec votre composant React racine, attend le flux, puis utilise c.body(stream, { headers: { 'Content-Type': 'text/html' } }) ou c.html(htmlString) pour envoyer la réponse. Le flux produit des fragments HTML que le navigateur peut afficher progressivement.

renderToReadableStream renvoie une promesse qui se résout en un ReadableStream de fragments HTML. Ce ReadableStream est conforme à l'interface Web Streams et peut être transmis directement comme corps d'un objet Response, ce qui en fait un choix idéal pour le gestionnaire fetch de Cloudflare Workers.

Le flux React produit le HTML de l'arbre des composants, mais pas celui du document environnant. Vous devez injecter le flux dans une structure HTML : une chaîne contenant le doctype, l'en-tête head avec les balises meta et le lien CSS, la balise body ouvrante, puis le flux React, et enfin les balises body et html fermantes.

Un ensemble de fichiers client React construit avec Vite doit être diffusé parallèlement au Worker. Cloudflare Pages ou la fonctionnalité Workers Assets s'en charge : c.env.ASSETS.fetch(request) achemine les requêtes de ressources (JS, CSS, images) vers les fichiers statiques téléversés avec le déploiement de votre Worker.

Le fichier d'entrée du Worker exporte un objet par défaut avec un gestionnaire fetch : export default { fetch: app.fetch }. La méthode app.fetch de Hono est déjà un gestionnaire fetch compatible qui reçoit une Request et renvoie une Response ; elle s'intègre donc directement à l'environnement d'exécution de Workers.

wrangler dev démarre un serveur de développement local qui émule l'environnement d'exécution de Cloudflare Workers sur votre machine. Il surveille les modifications des fichiers et recharge automatiquement l'application, offrant un cycle de développement local rapide avant le déploiement en production.

wrangler deploy regroupe et téléverse votre code Worker sur le réseau de Cloudflare, le rendant disponible dans plus de 300 emplacements en périphérie en quelques secondes. Le fichier de configuration wrangler.toml indique votre ID de compte, le nom du Worker ainsi que les liaisons vers les espaces de noms KV ou les bases de données D1.

Pour ajouter de l'interactivité côté client, transmettez bootstrapScripts: ['/assets/client.js'] à renderToReadableStream. React insérera une balise script dans le HTML afin de charger l'ensemble client et d'appeler hydrateRoot sur le DOM généré côté serveur, ce qui rend la page interactive après le chargement de JS.

Que renvoie renderToReadableStream ?

Hono fournit un cadriciel HTTP léger, conçu nativement pour la périphérie, qui s'intègre parfaitement à la fonction renderToReadableStream de React. Le point d'entrée du Worker exporte directement app.fetch vers l'environnement d'exécution de Workers, les ressources statiques sont diffusées par l'intermédiaire des liaisons ASSETS et wrangler gère à la fois le développement local et le déploiement en production. bootstrapScripts relie le HTML diffusé en flux à l'ensemble d'hydratation côté client.