Streaming en React 18: cómo funciona renderToPipeableStream

Antes de React 18, la representación en el servidor utilizaba renderToString, que es síncrono: React representa todo el árbol de componentes como una cadena antes de enviar HTML al navegador. Si algún componente carga datos, el servidor debe esperar a que todos estén disponibles antes de que el primer byte llegue al usuario.

React 18 introdujo renderToPipeableStream, que representa el árbol de componentes como un flujo de fragmentos HTML. En lugar de esperar a que todo esté listo, React envía el HTML a medida que completa cada parte del árbol, lo que permite al navegador comenzar a representar inmediatamente el contenido visible.

renderToPipeableStream devuelve un objeto con dos métodos: pipe(writable) y abort(). pipe acepta un flujo Writable de Node.js (normalmente la respuesta HTTP) y comienza a transmitirle HTML. abort() cancela el flujo y se utiliza cuando se cancela la solicitud o se supera el tiempo de espera.

El flujo comienza con el shell HTML: todo el contenido que no está bloqueado por un límite de Suspense pendiente. Esto incluye el encabezado del documento, la navegación, el pie de página, la estructura visual de la interfaz y cualquier contenido disponible de forma síncrona. El shell se transmite inmediatamente, antes de que se resuelvan los componentes que dependen de datos.

Los componentes dentro de límites de Suspense que esperan datos se transmiten inicialmente con su interfaz de fallback (por ejemplo, un indicador de carga). React envía después una etiqueta de script que reemplaza el fallback por el contenido resuelto, todo ello sin volver a renderizar el shell en el cliente.

Pase bootstrapScripts: ['/static/js/client.js'] a renderToPipeableStream para indicar a React que inserte una etiqueta de script al final del flujo. El navegador carga este bundle y llama a hydrateRoot, asociando los controladores de eventos de React al DOM renderizado en el servidor.

onShellReady se ejecuta cuando el shell HTML (todo lo que está fuera de los límites de Suspense pendientes) está listo para enviarse. Este es el momento correcto para llamar a pipe(res), pero es importante establecer el código de estado HTTP y los encabezados de respuesta antes de llamar a pipe, ya que la transmisión fija el estado HTTP.

Como el streaming comienza inmediatamente al llamar a pipe(), cualquier asignación a res.setHeader o res.statusCode debe realizarse antes de llamar a pipe. Un patrón habitual consiste en establecer el estado 200 y Content-Type: text/html en la devolución de llamada onShellReady y llamar inmediatamente después a pipe(res).

onShellError se ejecuta cuando ocurre un error irrecuperable antes de que el shell termine de renderizarse; por ejemplo, cuando un componente de nivel superior lanza una excepción fuera de cualquier límite de Suspense. En este caso, no puede transmitir una respuesta parcial; en su lugar, redirija a una página de error o envíe un documento HTML de error estático.

onAllReady se ejecuta cuando todo el árbol de React se ha resuelto, incluidos todos los límites de Suspense. Para los rastreadores de motores de búsqueda y las herramientas de vista previa de enlaces de redes sociales, debe enviar el HTML completo sin streaming. Compruebe si la solicitud proviene de un bot y llame a pipe(res) en onAllReady en lugar de hacerlo en onShellReady.

onError se ejecuta cuando se producen errores en los límites de Suspense; React aún puede transmitir el resto de la página mientras ese límite muestra su interfaz de error alternativa. Utilice onError para registrar el error en su canal de observabilidad sin abortar el streaming para el usuario.

¿Cuándo debe utilizar onAllReady en lugar de onShellReady para comenzar el streaming mediante pipe?

renderToPipeableStream es la primitiva de SSR mediante streaming de React 18 para servidores Node.js. Transmite el shell HTML inmediatamente mediante onShellReady, completa los límites de Suspense a medida que se resuelven los datos e hidrata el cliente mediante bootstrapScripts. Utilice onAllReady para bots y rastreadores, onShellError para fallos fatales y establezca siempre las cabeceras HTTP antes de llamar a pipe().