Streaming-SSR am Edge

Wenn ein Server HTML streamt, empfängt und rendert der Browser die Inhalte blockweise, anstatt auf das vollständige Dokument zu warten. Dadurch können Nutzer die sichtbaren Teile der Seite — Header, Navigation und Hero-Bereich — sehen und mit ihnen interagieren, während langsamere, datenabhängige Abschnitte noch geladen werden.

Wenn Sie bootstrapScripts an renderToReadableStream übergeben, teilen Sie React mit, wo sich das clientseitige JavaScript-Bundle befindet. React fügt am Ende des Streams ein Script-Tag ein, damit der Browser das Bundle lädt und hydrateRoot aufruft. So wird die Seite interaktiv, sobald die einzelnen Abschnitte gestreamt wurden.

React verwendet Suspense-Grenzen, um den Komponentenbaum in unabhängig streambare Abschnitte aufzuteilen. Komponenten innerhalb einer Suspense-Grenze, die auf Daten warten (über ein geworfenes Promise), werden zunächst als Platzhalter gestreamt und später durch ihre tatsächlichen Inhalte ersetzt.

Der onShellReady-Callback wird ausgelöst, sobald das HTML-Grundgerüst ohne ausgesetzte Inhalte — also alles außerhalb der Suspense-Grenzen — zum Streamen bereit ist. Dies ist der richtige Zeitpunkt, um den HTTP-Statuscode und die Response-Header festzulegen und anschließend pipe(res) aufzurufen oder mit dem Lesen aus dem ReadableStream zu beginnen.

HTTP-Statuscodes und Header müssen gesendet werden, bevor der Response-Body beginnt. Da das Streaming mit onShellReady startet, muss jede Fehlerbehandlungslogik — etwa das Setzen des Statuscodes 500 oder eine Weiterleitung — ausgeführt werden, bevor das Grundgerüst zu fließen beginnt. Sobald das Streaming begonnen hat, ist der Statuscode festgelegt.

onShellError wird ausgelöst, wenn ein schwerwiegender Fehler auftritt, bevor das Grundgerüst bereit ist — beispielsweise ein Fehler in einer übergeordneten Komponente außerhalb jeder Suspense-Grenze. In diesem Fall wird das Grundgerüst nie gestreamt, und Sie sollten mit einer statischen Fehlerseite antworten oder zu einer Fehlerroute weiterleiten.

onError wird bei behebbaren Fehlern innerhalb von Suspense-Grenzen ausgelöst. React kann den Rest der Seite weiterhin streamen; die fehlerhafte Grenze rendert ihre Fehler-Fallback-Oberfläche. Verwenden Sie onError für die Protokollierung: Erfassen Sie den Fehler in Ihrer Observability-Plattform, ohne den Stream abzubrechen.

Wenn die Daten einer Suspense-Grenze zu lange benötigen, streamen Sie die Shell trotzdem und lassen Sie die Grenze auf dem Client hydratisieren. Implementieren Sie ein Timeout: Rufen Sie nach 5 Sekunden abort() für den Stream auf, wenn die Grenze noch nicht aufgelöst wurde; der Client ruft die Daten dann selbst über useEffect ab.

Die Workers-Laufzeitumgebung übergibt den ReadableStream direkt als Response-Body. Die Infrastruktur von Cloudflare leitet jeden Chunk an den Browser des Benutzers weiter, sobald React ihn erzeugt, ohne das gesamte Dokument zu puffern. Das bedeutet, dass die ersten Bytes des HTML innerhalb von Millisekunden nach Eingang der Anfrage den Edge-PoP verlassen.

renderToReadableStream gibt eine Abort-Controller-Funktion zurück. Wenn die Anfrage abgebrochen wird (der Benutzer navigiert weg), stoppt der Aufruf von abort() React dabei, weiter zu rendern und Daten zu verarbeiten. Dadurch vermeiden Sie unnötige Berechnungen für verwaiste Anfragen und halten die CPU-Nutzung des Workers begrenzt.

Beim Edge-Streaming sieht die vollständige Latenzkette folgendermaßen aus: 5 ms (Anfrage zum nächstgelegenen PoP) + 2 ms (Cold Start des Workers) + 8 ms (Shell-Rendering) = 15 ms bis zum ersten Byte. Der Browser des Benutzers rendert das LCP-Element aus der Shell, während der Rest der Seite im Hintergrund weiter gestreamt wird.

Wann genau wird der onShellReady-Callback während des Streaming-SSR aufgerufen?

Streaming-SSR vom Edge liefert HTML in Chunks und verbessert FCP und LCP, indem die Shell sofort gesendet wird. Suspense-Grenzen unterteilen den Baum in unabhängig streambare Abschnitte. onShellReady ist das Signal, mit dem das Piping gestartet wird — setzen Sie die Statuscodes, bevor Sie den Aufruf durchführen. onShellError verarbeitet fatale Fehler, onError behebbare Fehler, und abort() verhindert unnötige Arbeit bei abgebrochenen Anfragen.