React on Cloudflare Workers with Hono

Hono is a lightweight, ultra-fast web framework designed to run on edge runtimes including Cloudflare Workers, Deno Deploy, Bun, and Node.js. Its API is inspired by Express but built from the ground up for the Web Standards (Fetch API, Request/Response), making it a natural fit for edge environments.

Scaffolding a new Hono project for Cloudflare Workers is straightforward: npm create hono@latest prompts you to choose a template, select "cloudflare-workers", and creates a project pre-configured with wrangler (Cloudflare's CLI) and the Hono dependency.

To server-render React inside a Hono Worker, install react, react-dom, and @types/react, then import renderToReadableStream from react-dom/server. This function is part of React 18's streaming API and is designed for environments that support the Web Streams API — which Cloudflare Workers do.

A typical SSR route handler calls renderToReadableStream with your root React component, awaits the stream, then uses c.body(stream, { headers: { 'Content-Type': 'text/html' } }) or c.html(htmlString) to send the response. The stream produces HTML chunks that the browser can progressively render.

renderToReadableStream returns a Promise that resolves to a ReadableStream of HTML chunks. This ReadableStream conforms to the Web Streams API and can be passed directly as the body of a Response object, making it a perfect fit for the Cloudflare Workers fetch handler.

The React stream produces the component tree HTML but not the surrounding document. You must inject the stream into an HTML shell: a string containing the doctype, head with meta tags and the CSS link, opening body tag — then the React stream — then closing body and html tags.

A Vite-built React client bundle needs to be served alongside the Worker. Cloudflare Pages or the Workers Assets feature handles this: c.env.ASSETS.fetch(request) routes asset requests (JS, CSS, images) to the static files uploaded with your Worker deployment.

The Worker entry file exports a default object with a fetch handler: export default { fetch: app.fetch }. Hono's app.fetch method is already a compatible fetch handler that receives a Request and returns a Response, so it plugs directly into the Workers runtime.

wrangler dev starts a local development server that emulates the Cloudflare Workers runtime on your machine. It watches for file changes and reloads automatically, providing a fast local development loop before deploying to production.

wrangler deploy bundles and uploads your Worker code to Cloudflare's network, making it live at all 300+ edge locations within seconds. The wrangler.toml configuration file specifies your account ID, Worker name, and any KV namespace or D1 database bindings.

For client-side interactivity, pass bootstrapScripts: ['/assets/client.js'] to renderToReadableStream. React will inject a script tag into the HTML that loads the client bundle and calls hydrateRoot on the server-rendered DOM, making the page interactive after the JS loads.

What does renderToReadableStream return?

Hono provides a lightweight, edge-native HTTP framework that integrates cleanly with React's renderToReadableStream. The Worker entry exports app.fetch directly to the Workers runtime, static assets are served via ASSETS bindings, and wrangler handles both local dev and production deployment. bootstrapScripts connect the streamed HTML to the client-side hydration bundle.