Transmissão no React 18: como funciona renderToPipeableStream

Antes do React 18, a renderização no servidor usava renderToString, que é síncrono: o React renderiza toda a árvore de componentes em uma string antes de enviar qualquer HTML ao navegador. Se algum componente carregar dados, o servidor deverá aguardar todos os dados antes que o primeiro byte chegue ao usuário.

O React 18 introduziu renderToPipeableStream, que renderiza a árvore de componentes como um fluxo de blocos HTML. Em vez de aguardar tudo ficar pronto, o React envia HTML à medida que conclui cada parte da árvore, permitindo que o navegador comece a renderizar imediatamente o conteúdo visível.

renderToPipeableStream retorna um objeto com dois métodos: pipe(writable) e abort(). pipe aceita um fluxo gravável do Node.js (normalmente a resposta HTTP) e começa a transmitir HTML para ele. abort() cancela o fluxo, sendo usado quando a solicitação é cancelada ou quando um tempo limite é excedido.

O fluxo começa com a estrutura inicial HTML — todo o conteúdo que não está bloqueado por um limite Suspense pendente. Isso inclui o cabeçalho do documento, a navegação, o rodapé, os elementos estruturais do layout e qualquer conteúdo disponível de forma síncrona. A estrutura inicial é transmitida imediatamente, antes que qualquer componente dependente de dados seja resolvido.

Os componentes dentro de limites Suspense que aguardam dados são inicialmente transmitidos com sua interface de reserva (por exemplo, um indicador de carregamento). O React envia posteriormente um elemento script que substitui a interface de reserva pelo conteúdo resolvido — tudo isso sem uma nova renderização da estrutura inicial no cliente.

Passe bootstrapScripts: ['/static/js/client.js'] para renderToPipeableStream para informar ao React que deve injetar um elemento script no final do fluxo. O navegador carrega esse pacote e chama hydrateRoot, associando os manipuladores de eventos do React ao DOM renderizado no servidor.

onShellReady é acionado quando a estrutura inicial HTML (tudo fora dos limites Suspense pendentes) está pronta para ser enviada. Esse é o momento correto para chamar pipe(res) — mas, principalmente, defina o código de status HTTP e os cabeçalhos da resposta antes de chamar pipe, pois a transmissão fixa o status HTTP.

Como a transmissão em fluxo começa imediatamente quando você chama pipe(), qualquer atribuição a res.setHeader ou res.statusCode deve acontecer antes da chamada a pipe. Um padrão comum é definir o status como 200 e Content-Type: text/html no retorno de chamada onShellReady e, em seguida, chamar pipe(res) imediatamente.

onShellError é acionado quando ocorre um erro irrecuperável antes de a estrutura inicial terminar de ser renderizada — por exemplo, quando um componente de nível superior lança um erro fora de qualquer limite Suspense. Nesse caso, você não pode transmitir uma resposta parcial; em vez disso, redirecione para uma página de erro ou envie um documento HTML estático de erro.

onAllReady é acionado quando toda a árvore do React foi resolvida — incluindo todos os limites Suspense. Para rastreadores de mecanismos de busca e ferramentas de visualização prévia de links em redes sociais, convém enviar o HTML completo sem transmissão em fluxo. Verifique se a solicitação vem de um robô e chame pipe(res) em onAllReady, em vez de onShellReady.

onError é acionado para erros nos limites Suspense — o React ainda pode transmitir o restante da página enquanto esse limite exibe sua interface alternativa de erro. Use onError para registrar o erro no seu fluxo de observabilidade sem interromper a transmissão para o usuário.

Quando você deve usar onAllReady em vez de onShellReady para iniciar o envio por pipe?

renderToPipeableStream é a primitiva de SSR em transmissão em fluxo do React 18 para servidores Node.js. Ela transmite a estrutura inicial do HTML imediatamente por meio de onShellReady, preenche os limites Suspense conforme os dados são resolvidos e hidrata o cliente por meio de bootstrapScripts. Use onAllReady para robôs e rastreadores, onShellError para falhas fatais e sempre defina os cabeçalhos HTTP antes de chamar pipe().