SSR en streaming desde el edge

Cuando un servidor transmite HTML, el navegador recibe y renderiza el contenido por fragmentos en lugar de esperar al documento completo. Esto permite que los usuarios vean e interactúen con las partes visibles de la página —el encabezado, la navegación y la sección principal— mientras las secciones más lentas que dependen de datos siguen cargándose.

Pasar bootstrapScripts a renderToReadableStream indica a React dónde se encuentra el bundle de JavaScript del lado del cliente. React inyecta una etiqueta de script al final del stream para que el navegador cargue el bundle y llame a hydrateRoot, haciendo que la página sea interactiva a medida que termina de transmitirse cada sección.

El streaming de React se basa en los límites de Suspense para dividir el árbol de componentes en secciones que se pueden transmitir de forma independiente. Los componentes dentro de un límite de Suspense que esperan datos (mediante una Promise lanzada) se transmiten primero como placeholders; después, cuando se resuelven, transmiten su contenido real.

El callback onShellReady se ejecuta cuando el shell HTML sin suspensiones —todo lo que está fuera de los límites de Suspense— está listo para transmitirse. Ese es el momento correcto para establecer el código de estado HTTP y las cabeceras de respuesta, y después llamar a pipe(res) o empezar a leer desde el ReadableStream.

Los códigos de estado HTTP y las cabeceras deben enviarse antes de que comience el body de la respuesta. Como el streaming se inicia con onShellReady, cualquier lógica de gestión de errores (establecer el estado 500 o redirigir) debe ejecutarse antes de que el shell empiece a transmitirse; una vez iniciado el streaming, el código de estado queda bloqueado.

onShellError se ejecuta cuando se produce un error fatal antes de que el shell esté listo, por ejemplo, un error en un componente de nivel superior situado fuera de cualquier límite de Suspense. En ese caso, el shell nunca se transmite y debe responder con una página de error estática o redirigir a una ruta de error.

onError se ejecuta cuando se producen errores recuperables dentro de los límites de Suspense. React aún puede transmitir el resto de la página; el límite afectado por el error renderiza su UI alternativa de error. Utilice onError para el logging: capture el error en su plataforma de observabilidad sin abortar el stream.

Si los datos de un límite de Suspense tardan demasiado, transmita el shell de todos modos y deje que el límite se hidrate en el cliente. Implemente un tiempo de espera: después de 5 segundos, llame a abort() sobre el stream si el límite no se ha resuelto, y el cliente obtendrá los datos por su cuenta mediante useEffect.

El runtime de Workers pasa ReadableStream directamente como cuerpo de Response. La infraestructura de Cloudflare reenvía cada fragmento al navegador del usuario a medida que React lo produce, sin almacenar en búfer todo el documento. Esto significa que los primeros bytes de HTML salen del PoP de edge en cuestión de milisegundos desde la llegada de la solicitud.

renderToReadableStream devuelve una función para abortar. Si se cancela la solicitud (por ejemplo, porque el usuario navega a otra página), llamar a abort() detiene la renderización y el procesamiento de datos adicionales por parte de React. Esto evita desperdiciar capacidad de cómputo en solicitudes huérfanas y mantiene acotado el uso de CPU del Worker.

Con el streaming desde el edge, la cadena completa de latencia es la siguiente: 5 ms (de la solicitud al PoP más cercano) + 2 ms (inicio en frío del Worker) + 8 ms (renderización del shell) = 15 ms hasta el primer byte. El navegador del usuario renderiza el elemento LCP a partir del shell mientras el resto de la página continúa transmitiéndose en segundo plano.

¿Cuándo se ejecuta exactamente la devolución de llamada onShellReady durante el SSR mediante streaming?

El SSR mediante streaming desde el edge entrega HTML en fragmentos, lo que mejora FCP y LCP al enviar el shell de inmediato. Los límites de Suspense dividen el árbol en secciones que se pueden transmitir de forma independiente. onShellReady indica que debe comenzar el envío mediante pipes; establezca los códigos de estado antes de llamarlo. onShellError gestiona los fallos irreversibles, onError gestiona los recuperables y abort() evita desperdiciar trabajo en solicitudes canceladas.