SSR in streaming dall’edge

Quando un server trasmette HTML in streaming, il browser riceve e renderizza i contenuti a blocchi invece di attendere il documento completo. In questo modo gli utenti vedono e possono usare le parti visibili della pagina, come l'intestazione, la navigazione e la sezione hero, mentre le sezioni più lente e dipendenti dai dati sono ancora in caricamento.

Passare bootstrapScripts a renderToReadableStream indica a React dove si trova il bundle JavaScript lato client. React inserisce un tag script alla fine dello stream, così il browser carica il bundle e chiama hydrateRoot, rendendo interattiva la pagina man mano che ogni sezione completa lo streaming.

Lo streaming di React si basa sui confini Suspense per suddividere l'albero dei componenti in sezioni che possono essere trasmesse indipendentemente. I componenti all'interno di un confine Suspense che attendono dati (tramite una Promise lanciata) vengono trasmessi inizialmente come segnaposto, quindi vengono risolti e il loro contenuto effettivo viene trasmesso in seguito.

Il callback onShellReady viene eseguito quando lo shell HTML non sospeso, cioè tutto ciò che si trova al di fuori dei confini Suspense, è pronto per lo streaming. Questo è il momento corretto per impostare il codice di stato HTTP e gli header della risposta, quindi chiamare pipe(res) o iniziare a leggere dal ReadableStream.

I codici di stato HTTP e gli header devono essere inviati prima che inizi il corpo della risposta. Poiché lo streaming inizia con onShellReady, qualsiasi logica di gestione degli errori (impostare lo stato 500, reindirizzare) deve essere eseguita prima che lo shell inizi a fluire: una volta iniziato lo streaming, il codice di stato è definitivo.

onShellError viene eseguito quando si verifica un errore irreversibile prima che lo shell sia pronto, ad esempio un errore in un componente di livello superiore al di fuori di qualsiasi confine Suspense. In questo caso lo shell non viene mai trasmesso e dovrebbe rispondere con una pagina di errore statica o reindirizzare a una route di errore.

onError viene eseguito per gli errori recuperabili all'interno dei confini Suspense. React può comunque trasmettere il resto della pagina; il confine che ha generato l'errore renderizza la relativa interfaccia di fallback. Usi onError per la registrazione: acquisisca l'errore nella piattaforma di osservabilità senza interrompere lo stream.

Se i dati di un boundary Suspense richiedono troppo tempo, trasmetta comunque la shell e lasci che il boundary venga idratato sul client. Implementi un timeout: dopo 5 secondi, chiami abort() sullo stream se il boundary non è stato risolto; il client recupererà autonomamente i dati tramite useEffect.

Il runtime di Workers passa direttamente ReadableStream come corpo della Response. L'infrastruttura di Cloudflare inoltra ogni chunk al browser dell'utente man mano che React lo produce, senza bufferizzare l'intero documento. Ciò significa che i primi byte di HTML lasciano il PoP edge entro pochi millisecondi dall'arrivo della richiesta.

renderToReadableStream restituisce una funzione per interrompere il rendering. Se la richiesta viene annullata, ad esempio perché l'utente cambia pagina, chiamando abort() si impedisce a React di continuare a eseguire il rendering e a elaborare i dati. In questo modo si evitano calcoli sprecati per richieste orfane e si mantiene entro limiti prevedibili l'utilizzo della CPU del Worker.

Con lo streaming edge, la catena completa della latenza è la seguente: 5 ms (dalla richiesta al PoP più vicino) + 2 ms (avvio a freddo del Worker) + 8 ms (rendering della shell) = 15 ms al primo byte. Il browser dell'utente esegue il rendering dell'elemento LCP dalla shell, mentre il resto della pagina continua a essere trasmesso in streaming in background.

Lo streaming SSR dall'edge consegna l'HTML in chunk, migliorando FCP e LCP perché invia immediatamente la shell. I boundary Suspense dividono l'albero in sezioni che possono essere trasmesse in streaming indipendentemente. onShellReady segnala che è possibile iniziare il piping: imposti i codici di stato prima di chiamarlo. onShellError gestisce gli errori fatali, onError quelli recuperabili e abort() evita di sprecare lavoro per le richieste annullate.