React auf Cloudflare Workers mit Hono

Hono ist ein leichtgewichtiges, extrem schnelles Web-Framework, das für Edge-Runtimes wie Cloudflare Workers, Deno Deploy, Bun und Node.js entwickelt wurde. Seine API ist von Express inspiriert, wurde aber von Grund auf für die Webstandards (Fetch API, Request/Response) entwickelt und eignet sich daher besonders gut für Edge-Umgebungen.

Das Anlegen eines neuen Hono-Projekts für Cloudflare Workers ist unkompliziert: npm create hono@latest fordert Sie auf, ein Template auszuwählen, "cloudflare-workers" zu wählen, und erstellt ein Projekt, das bereits mit wrangler (der CLI von Cloudflare) und der Hono-Abhängigkeit konfiguriert ist.

Um React innerhalb eines Hono Workers serverseitig zu rendern, installieren Sie react, react-dom und @types/react und importieren anschließend renderToReadableStream aus react-dom/server. Diese Funktion gehört zur Streaming-API von React 18 und ist für Umgebungen ausgelegt, die die Web Streams API unterstützen — und das tun Cloudflare Workers.

Ein typischer SSR-Routen-Handler ruft renderToReadableStream mit Ihrer React-Root-Komponente auf, wartet auf den Stream und verwendet anschließend c.body(stream, { headers: { 'Content-Type': 'text/html' } }) oder c.html(htmlString), um die Antwort zu senden. Der Stream erzeugt HTML-Blöcke, die der Browser schrittweise rendern kann.

renderToReadableStream gibt ein Promise zurück, das zu einem ReadableStream mit HTML-Blöcken aufgelöst wird. Dieser ReadableStream entspricht der Web Streams API und kann direkt als Body eines Response-Objekts verwendet werden. Damit eignet er sich ideal für den fetch-Handler von Cloudflare Workers.

Der React-Stream erzeugt das HTML des Komponentenbaums, aber nicht das umgebende Dokument. Sie müssen den Stream in ein HTML-Grundgerüst einfügen: einen String mit dem Doctype, dem head-Element mit Meta-Tags und dem CSS-Link sowie dem öffnenden body-Tag — anschließend den React-Stream — und danach den schließenden body- und html-Tags.

Ein mit Vite erstelltes React-Client-Bundle muss zusammen mit dem Worker ausgeliefert werden. Cloudflare Pages oder die Workers-Assets-Funktion übernimmt dies: c.env.ASSETS.fetch(request) leitet Asset-Anfragen (JS, CSS, Bilder) an die statischen Dateien weiter, die mit Ihrem Worker-Deployment hochgeladen wurden.

Die Einstiegspunktdatei des Workers exportiert ein Standardobjekt mit einem fetch-Handler: export default { fetch: app.fetch }. Die Methode app.fetch von Hono ist bereits ein kompatibler fetch-Handler, der einen Request empfängt und eine Response zurückgibt. Sie lässt sich daher direkt in die Workers-Runtime einbinden.

wrangler dev startet auf Ihrem Rechner einen lokalen Entwicklungsserver, der die Cloudflare-Workers-Runtime emuliert. Der Server überwacht Dateiänderungen und lädt automatisch neu. So erhalten Sie einen schnellen lokalen Entwicklungszyklus, bevor Sie in die Produktion deployen.

wrangler deploy bündelt Ihren Worker-Code und lädt ihn in das Netzwerk von Cloudflare hoch. Dadurch ist er innerhalb weniger Sekunden an mehr als 300 Edge-Standorten verfügbar. Die Konfigurationsdatei wrangler.toml legt Ihre Konto-ID, den Namen des Workers sowie alle KV-Namespace- oder D1-Datenbank-Bindings fest.

Übergeben Sie bootstrapScripts: ['/assets/client.js'] an renderToReadableStream, um clientseitige Interaktivität zu ermöglichen. React fügt ein Script-Tag in das HTML ein, das das Client-Bundle lädt und hydrateRoot auf dem serverseitig gerenderten DOM aufruft. Dadurch wird die Seite interaktiv, sobald das JavaScript geladen ist.

Was gibt renderToReadableStream zurück?

Hono stellt ein leichtgewichtiges, für Edge-Umgebungen optimiertes HTTP-Framework bereit, das sich nahtlos in Reacts renderToReadableStream integrieren lässt. Der Worker-Einstiegspunkt exportiert app.fetch direkt an die Workers-Runtime, statische Assets werden über ASSETS-Bindings ausgeliefert, und wrangler übernimmt sowohl die lokale Entwicklung als auch das Deployment in die Produktion. bootstrapScripts verbindet das gestreamte HTML mit dem clientseitigen Hydration-Bundle.