React su Cloudflare Workers con Hono

Hono è un framework web leggero e velocissimo, progettato per essere eseguito su runtime edge tra cui Cloudflare Workers, Deno Deploy, Bun e Node.js. La sua API si ispira a Express, ma è stata progettata da zero per gli standard Web (Fetch API, Request/Response), il che la rende particolarmente adatta agli ambienti edge.

Creare lo scheletro di un nuovo progetto Hono per Cloudflare Workers è semplice: npm create hono@latest chiede di scegliere un template, selezionare "cloudflare-workers" e crea un progetto preconfigurato con wrangler (la CLI di Cloudflare) e la dipendenza Hono.

Per eseguire il rendering server-side di React all'interno di un Worker Hono, installi react, react-dom e @types/react, quindi importi renderToReadableStream da react-dom/server. Questa funzione fa parte dell'API di streaming di React 18 ed è progettata per gli ambienti che supportano la Web Streams API, come Cloudflare Workers.

Un tipico gestore di route SSR chiama renderToReadableStream con il componente React radice, attende lo stream e poi usa c.body(stream, { headers: { 'Content-Type': 'text/html' } }) oppure c.html(htmlString) per inviare la risposta. Lo stream produce blocchi di HTML che il browser può renderizzare progressivamente.

renderToReadableStream restituisce una Promise che si risolve in un ReadableStream di blocchi HTML. Questo ReadableStream è conforme alla Web Streams API e può essere passato direttamente come body di un oggetto Response, rendendolo perfetto per il gestore fetch di Cloudflare Workers.

Lo stream React produce l'HTML dell'albero dei componenti, ma non il documento circostante. Deve inserire lo stream in uno shell HTML: una stringa contenente il doctype, l'head con i meta tag e il collegamento al CSS, il tag body di apertura, quindi lo stream React, seguito dai tag body e html di chiusura.

Un bundle client React compilato da Vite deve essere servito insieme al Worker. Cloudflare Pages o la funzionalità Workers Assets gestisce questo aspetto: c.env.ASSETS.fetch(request) inoltra le richieste degli asset (JS, CSS, immagini) ai file statici caricati con il deployment del Worker.

Il file di ingresso del Worker esporta un oggetto predefinito con un gestore fetch: export default { fetch: app.fetch }. Il metodo app.fetch di Hono è già un gestore fetch compatibile che riceve una Request e restituisce una Response, quindi si integra direttamente con il runtime Workers.

wrangler dev avvia un server di sviluppo locale che emula il runtime Cloudflare Workers sul computer. Monitora le modifiche ai file e ricarica automaticamente l'applicazione, offrendo un ciclo di sviluppo locale rapido prima della distribuzione in produzione.

wrangler deploy raggruppa e carica il codice del Worker nella rete Cloudflare, rendendolo disponibile in oltre 300 località edge in pochi secondi. Il file di configurazione wrangler.toml specifica l'ID dell'account, il nome del Worker e gli eventuali binding per namespace KV o database D1.

Per aggiungere l'interattività lato client, passi bootstrapScripts: ['/assets/client.js'] a renderToReadableStream. React inserirà nell'HTML un tag script che carica il bundle client e chiama hydrateRoot sul DOM renderizzato dal server, rendendo interattiva la pagina dopo il caricamento di JS.

Che cosa restituisce renderToReadableStream?

Hono offre un framework HTTP leggero e nativo per l'edge, che si integra perfettamente con renderToReadableStream di React. Il punto di ingresso del Worker esporta direttamente app.fetch nel runtime Workers, gli asset statici vengono serviti tramite i binding ASSETS e wrangler gestisce sia lo sviluppo locale sia la distribuzione in produzione. bootstrapScripts collega l'HTML trasmesso in streaming al bundle di hydration lato client.