Streaming in React 18: come funziona renderToPipeableStream

Prima di React 18, il rendering lato server utilizzava renderToString, che è sincrono: React esegue il rendering dell'intero albero dei componenti in una stringa prima di inviare qualsiasi HTML al browser. Se un componente carica dati, il server deve attendere che tutti i dati siano disponibili prima che il primo byte raggiunga l'utente.

React 18 ha introdotto renderToPipeableStream, che esegue il rendering dell'albero dei componenti come flusso di blocchi HTML. Invece di attendere che tutto sia pronto, React invia l'HTML man mano che completa ogni parte dell'albero, consentendo al browser di iniziare immediatamente a visualizzare il contenuto visibile.

renderToPipeableStream restituisce un oggetto con due metodi: pipe(writable) e abort(). pipe accetta un flusso Writable di Node.js, in genere la risposta HTTP, e avvia lo streaming dell'HTML al suo interno. abort() annulla il flusso e viene utilizzato quando la richiesta viene annullata o si supera un timeout.

Il flusso inizia con lo shell HTML, cioè tutto il contenuto che non è bloccato da un boundary Suspense in attesa. Include l'head del documento, la navigazione, il footer, la struttura del layout e qualsiasi contenuto disponibile sincronicamente. Lo shell viene trasmesso immediatamente, prima che vengano risolti i componenti dipendenti dai dati.

I componenti all'interno dei boundary Suspense in attesa di dati vengono inizialmente trasmessi con la relativa UI di fallback (ad esempio, uno spinner di caricamento). In seguito React invia un tag script che sostituisce il fallback con il contenuto risolto, senza alcun nuovo rendering lato client dello shell.

Passi bootstrapScripts: ['/static/js/client.js'] a renderToPipeableStream per indicare a React di inserire un tag script alla fine del flusso. Il browser carica questo bundle e chiama hydrateRoot, associando i gestori degli eventi di React al DOM renderizzato dal server.

onShellReady viene eseguito quando lo shell HTML, cioè tutto ciò che si trova al di fuori dei boundary Suspense in attesa, è pronto per essere inviato. Questo è il momento corretto per chiamare pipe(res), ma è importante impostare il codice di stato HTTP e gli header della risposta prima di chiamare pipe, poiché lo streaming fissa il codice di stato HTTP.

Poiché lo streaming inizia immediatamente quando si chiama pipe(), qualsiasi assegnazione a res.setHeader o res.statusCode deve avvenire prima della chiamata a pipe. Un pattern comune consiste nell'impostare lo stato 200 e Content-Type: text/html nel callback onShellReady, quindi chiamare subito dopo pipe(res).

onShellError viene invocato quando si verifica un errore irreversibile prima che la shell abbia terminato il rendering, ad esempio quando un componente di primo livello genera un'eccezione al di fuori di qualsiasi confine Suspense. In questo caso non è possibile trasmettere una risposta parziale; è invece necessario reindirizzare a una pagina di errore o inviare un documento HTML statico di errore.

onAllReady viene invocato quando l'intero albero React è stato risolto, inclusi tutti i confini Suspense. Per i crawler dei motori di ricerca e i sistemi che generano anteprime dei link sui social media, è necessario inviare l'HTML completo senza streaming. Verifichi se la richiesta proviene da un bot e chiami pipe(res) in onAllReady invece che in onShellReady.

onError viene invocato per gli errori nei confini Suspense: React può continuare a trasmettere il resto della pagina mentre quel confine mostra la propria interfaccia di errore. Utilizzi onError per registrare l'errore nella pipeline di osservabilità senza interrompere lo streaming per l'utente.

Quando è opportuno usare onAllReady invece di onShellReady per iniziare a trasmettere la risposta?

renderToPipeableStream è la primitiva di React 18 per il rendering SSR in streaming sui server Node.js. Trasmette immediatamente la shell HTML tramite onShellReady, completa i confini Suspense man mano che i dati vengono risolti e idrata il client tramite bootstrapScripts. Utilizzi onAllReady per bot e crawler, onShellError per gli errori fatali e imposti sempre gli header HTTP prima di chiamare pipe().