React no Cloudflare Workers com Hono

Hono é uma estrutura web leve e ultrarrápida, projetada para ser executada em ambientes de execução na borda, incluindo Cloudflare Workers, Deno Deploy, Bun e Node.js. Sua API é inspirada no Express, mas foi criada desde o início para os padrões da Web (Fetch API, Request/Response), o que a torna uma escolha natural para ambientes de borda.

Criar a estrutura de um novo projeto Hono para Cloudflare Workers é simples: npm create hono@latest solicita que você escolha um modelo, selecione "cloudflare-workers" e cria um projeto pré-configurado com wrangler (a CLI da Cloudflare) e a dependência Hono.

Para renderizar React no servidor dentro de um Worker Hono, instale react, react-dom e @types/react; depois, importe renderToReadableStream de react-dom/server. Essa função faz parte da API de transmissão em fluxo do React 18 e foi projetada para ambientes compatíveis com a API de fluxos da Web — como o Cloudflare Workers.

Um manipulador de rotas SSR típico chama renderToReadableStream com seu componente React raiz, aguarda o fluxo e então usa c.body(stream, { headers: { 'Content-Type': 'text/html' } }) ou c.html(htmlString) para enviar a resposta. O fluxo produz blocos de HTML que o navegador pode renderizar progressivamente.

renderToReadableStream retorna uma promessa que é resolvida com um ReadableStream de blocos de HTML. Esse ReadableStream está em conformidade com a API de fluxos da Web e pode ser passado diretamente como o corpo de um objeto Response, sendo ideal para o manipulador fetch do Cloudflare Workers.

O fluxo React produz o HTML da árvore de componentes, mas não o documento ao redor. Você precisa inserir o fluxo em um esqueleto HTML: uma string contendo a declaração do tipo de documento, o cabeçalho com metatags e o link CSS, a tag de abertura do corpo — depois o fluxo React — e, por fim, as tags de fechamento do corpo e do HTML.

Um pacote cliente React criado com Vite precisa ser fornecido junto com o Worker. O Cloudflare Pages ou o recurso Assets dos Workers cuida disso: c.env.ASSETS.fetch(request) encaminha as solicitações de recursos (JS, CSS e imagens) para os arquivos estáticos enviados com a implantação do Worker.

O arquivo de entrada do Worker exporta um objeto padrão com um manipulador fetch: export default { fetch: app.fetch }. O método app.fetch do Hono já é um manipulador fetch compatível, que recebe uma Request e retorna uma Response, portanto ele se conecta diretamente ao ambiente de execução do Workers.

wrangler dev inicia um servidor de desenvolvimento local que emula o ambiente de execução do Cloudflare Workers em sua máquina. Ele observa alterações nos arquivos e recarrega automaticamente, proporcionando um ciclo rápido de desenvolvimento local antes da implantação em produção.

wrangler deploy empacota e envia seu código do Worker para a rede da Cloudflare, disponibilizando-o em mais de 300 locais de borda em poucos segundos. O arquivo de configuração wrangler.toml especifica o ID da sua conta, o nome do Worker e quaisquer vinculações a namespaces KV ou bancos de dados D1.

Para adicionar interatividade no cliente, passe bootstrapScripts: ['/assets/client.js'] a renderToReadableStream. React inserirá uma tag de script no HTML que carrega o pacote cliente e chama hydrateRoot no DOM renderizado no servidor, tornando a página interativa depois que o JS for carregado.

O que renderToReadableStream retorna?

Hono fornece uma estrutura HTTP leve e nativa da borda que se integra perfeitamente a renderToReadableStream do React. O ponto de entrada do Worker exporta app.fetch diretamente para o ambiente de execução do Workers, os recursos estáticos são fornecidos por meio das vinculações ASSETS e o wrangler cuida tanto do desenvolvimento local quanto da implantação em produção. bootstrapScripts conecta o HTML transmitido em fluxo ao pacote de hidratação no cliente.