React en Cloudflare Workers con Hono

Hono es un framework web ligero y ultrarrápido diseñado para ejecutarse en entornos de ejecución en el edge, incluidos Cloudflare Workers, Deno Deploy, Bun y Node.js. Su API está inspirada en Express, pero se ha creado desde cero para los estándares web (Fetch API, Request/Response), lo que lo convierte en una opción natural para los entornos edge.

Crear el esqueleto de un proyecto nuevo de Hono para Cloudflare Workers es sencillo: npm create hono@latest le solicita que elija una plantilla, seleccione "cloudflare-workers" y crea un proyecto preconfigurado con wrangler (la CLI de Cloudflare) y la dependencia de Hono.

Para renderizar React en el servidor dentro de un Worker de Hono, instale react, react-dom y @types/react; después, importe renderToReadableStream desde react-dom/server. Esta función forma parte de la API de streaming de React 18 y está diseñada para entornos compatibles con la API de Web Streams, como Cloudflare Workers.

Un handler de rutas SSR habitual llama a renderToReadableStream con su componente raíz de React, espera el stream y después utiliza c.body(stream, { headers: { 'Content-Type': 'text/html' } }) o c.html(htmlString) para enviar la respuesta. El stream produce fragmentos de HTML que el navegador puede renderizar progresivamente.

renderToReadableStream devuelve una Promise que se resuelve en un ReadableStream de fragmentos de HTML. Este ReadableStream cumple con la API de Web Streams y se puede pasar directamente como body de un objeto Response, por lo que encaja perfectamente con el fetch handler de Cloudflare Workers.

El stream de React produce el HTML del árbol de componentes, pero no el documento que lo rodea. Debe insertar el stream en un shell HTML: una cadena que contenga el doctype, el head con las metaetiquetas y el enlace al CSS, la etiqueta de apertura de body; después, el stream de React; y, finalmente, las etiquetas de cierre de body y html.

Un bundle de cliente de React creado con Vite debe servirse junto con el Worker. Cloudflare Pages o la función Workers Assets se encargan de esto: c.env.ASSETS.fetch(request) dirige las solicitudes de recursos (JS, CSS e imágenes) a los archivos estáticos subidos con su despliegue del Worker.

El archivo de entrada del Worker exporta un objeto predeterminado con un fetch handler: export default { fetch: app.fetch }. El método app.fetch de Hono ya es un fetch handler compatible que recibe un Request y devuelve un Response, por lo que se conecta directamente al entorno de ejecución de Workers.

wrangler dev inicia un servidor de desarrollo local que emula el entorno de ejecución de Cloudflare Workers en su máquina. Supervisa los cambios en los archivos y vuelve a cargar la aplicación automáticamente, lo que proporciona un ciclo de desarrollo local rápido antes de desplegar en producción.

wrangler deploy empaqueta y sube su código del Worker a la red de Cloudflare, dejándolo disponible en las más de 300 ubicaciones del edge en cuestión de segundos. El archivo de configuración wrangler.toml especifica su ID de cuenta, el nombre del Worker y cualquier binding de un namespace de KV o de una base de datos D1.

Para añadir interactividad del lado del cliente, pase bootstrapScripts: ['/assets/client.js'] a renderToReadableStream. React inyectará una etiqueta de script en el HTML que carga el bundle del cliente y llama a hydrateRoot sobre el DOM renderizado en el servidor, haciendo que la página sea interactiva después de cargar el JS.

¿Qué devuelve renderToReadableStream?

Hono proporciona un framework HTTP ligero y nativo del edge que se integra perfectamente con renderToReadableStream de React. El punto de entrada del Worker exporta app.fetch directamente al entorno de ejecución de Workers, los recursos estáticos se sirven mediante bindings de ASSETS y wrangler gestiona tanto el desarrollo local como el despliegue en producción. bootstrapScripts conecta el HTML transmitido por streaming con el bundle de hidratación del lado del cliente.