SSR com transmissão a partir da borda

Quando um servidor transmite HTML em fluxo, o navegador recebe e renderiza o conteúdo em blocos, em vez de esperar pelo documento completo. Isso significa que os usuários podem ver e utilizar as partes visíveis da página — o cabeçalho, a navegação e a seção principal — enquanto as seções mais lentas, dependentes de dados, ainda estão sendo carregadas.

Passar bootstrapScripts a renderToReadableStream informa ao React onde está o pacote JS do cliente. React insere uma tag de script no final do fluxo para que o navegador carregue o pacote e chame hydrateRoot, tornando a página interativa à medida que cada seção termina de ser transmitida.

A transmissão em fluxo do React depende dos limites de Suspense para dividir a árvore de componentes em seções que podem ser transmitidas de forma independente. Os componentes dentro de um limite de Suspense que estão aguardando dados (por meio de uma Promise lançada) são transmitidos primeiro como espaços reservados; depois, são resolvidos e seu conteúdo real é transmitido.

A função de retorno onShellReady é executada quando o esqueleto HTML sem suspensão — tudo que está fora dos limites de Suspense — está pronto para ser transmitido. Esse é o momento correto para definir o código de status HTTP e os cabeçalhos da resposta e, em seguida, chamar pipe(res) ou começar a ler o ReadableStream.

Os códigos de status e os cabeçalhos HTTP devem ser enviados antes do início do corpo da resposta. Como a transmissão começa com onShellReady, qualquer lógica de tratamento de erros (definir o status 500 ou redirecionar) precisa ser executada antes que o esqueleto comece a ser transmitido — depois que a transmissão começa, o código de status fica bloqueado.

onShellError é executado quando ocorre um erro fatal antes que o esqueleto esteja pronto — por exemplo, um erro em um componente de nível superior fora de qualquer limite de Suspense. Nesse caso, o esqueleto nunca é transmitido, e você deve responder com uma página de erro estática ou redirecionar para uma rota de erro.

onError é executado para erros recuperáveis dentro dos limites de Suspense. React ainda pode transmitir o restante da página; o limite que apresentou erro renderiza sua interface de usuário alternativa para erros. Use onError para registrar informações: capture o erro em sua plataforma de observabilidade sem interromper a transmissão.

Se os dados de um limite do Suspense demorarem demais, transmita a estrutura inicial mesmo assim e permita que o limite seja hidratado no cliente. Implemente um tempo limite: após 5 segundos, chame abort() no fluxo se o limite ainda não tiver sido resolvido; então, o cliente buscará os dados por conta própria usando useEffect.

O ambiente de execução dos Workers passa o ReadableStream diretamente como corpo da Response. A infraestrutura da Cloudflare encaminha cada bloco para o navegador do usuário à medida que o React o produz, sem armazenar o documento inteiro em buffer. Isso significa que os primeiros bytes de HTML saem do PoP de borda poucos milissegundos depois que a solicitação chega.

renderToReadableStream retorna uma função controladora de cancelamento. Se a solicitação for cancelada (porque o usuário navegar para outra página), chamar abort() impede que o React continue renderizando e processando dados. Isso evita computação desperdiçada em solicitações órfãs e mantém limitado o uso de CPU do Worker.

Com a transmissão na borda, a cadeia completa de latência é: 5 ms (da solicitação ao PoP mais próximo) + 2 ms (inicialização a frio do Worker) + 8 ms (renderização da estrutura inicial) = 15 ms até o primeiro byte. O navegador do usuário renderiza o elemento LCP a partir da estrutura inicial enquanto o restante da página continua sendo transmitido em segundo plano.

Em que momento exatamente a função de retorno onShellReady é acionada durante a SSR por transmissão contínua?

A SSR por transmissão contínua na borda entrega HTML em blocos, melhorando FCP e LCP ao enviar imediatamente a estrutura inicial. Os limites do Suspense dividem a árvore em seções que podem ser transmitidas de forma independente. onShellReady é o sinal para começar a encaminhar os dados — defina os códigos de status antes de chamá-lo. onShellError trata falhas fatais, onError trata falhas recuperáveis e abort() evita trabalho desperdiçado em solicitações canceladas.