Streaming in React 18: So funktioniert renderToPipeableStream

Vor React 18 wurde beim serverseitigen Rendern renderToString verwendet, das synchron arbeitet: React rendert den gesamten Komponentenbaum als String, bevor HTML an den Browser gesendet wird. Wenn eine Komponente Daten lädt, muss der Server auf alle Daten warten, bevor das erste Byte den Benutzer erreicht.

React 18 führte renderToPipeableStream ein, das den Komponentenbaum als Stream von HTML-Chunks rendert. Statt zu warten, bis alles bereit ist, sendet React HTML, sobald jeder Teil des Baums fertig ist, sodass der Browser sofort mit dem Rendern sichtbarer Inhalte beginnen kann.

renderToPipeableStream gibt ein Objekt mit zwei Methoden zurück: pipe(writable) und abort(). pipe akzeptiert einen Node.js-Writable-Stream (typischerweise die HTTP-Antwort) und beginnt, HTML in ihn zu streamen. abort() bricht den Stream ab und wird verwendet, wenn die Anfrage abgebrochen oder ein Timeout überschritten wird.

Der Stream beginnt mit der HTML-Shell – allen Inhalten, die nicht durch eine ausstehende Suspense-Boundary blockiert sind. Dazu gehören der Dokument-Head, die Navigation, der Footer, das Layout-Chrome und alle synchron verfügbaren Inhalte. Die Shell wird sofort gestreamt, bevor datenabhängige Komponenten aufgelöst sind.

Komponenten innerhalb von Suspense-Boundaries, die auf Daten warten, werden zunächst als ihre Fallback-UI gestreamt (z. B. ein Ladeindikator). React sendet später ein Script-Tag, das den Fallback durch den aufgelösten Inhalt ersetzt – und das alles ohne clientseitiges erneutes Rendern der Shell.

Übergeben Sie bootstrapScripts: ['/static/js/client.js'] an renderToPipeableStream, um React mitzuteilen, dass am Ende des Streams ein Script-Tag eingefügt werden soll. Der Browser lädt dieses Bundle und ruft hydrateRoot auf, wodurch die Event-Handler von React an das serverseitig gerenderte DOM angehängt werden.

onShellReady wird ausgelöst, wenn die HTML-Shell (alles außerhalb ausstehender Suspense-Boundaries) zum Senden bereit ist. Dies ist der richtige Zeitpunkt für pipe(res) – wichtig ist jedoch, den HTTP-Statuscode und die Response-Header vor dem Aufruf von pipe zu setzen, da das Streaming den HTTP-Status festschreibt.

Da das Streaming unmittelbar beginnt, sobald Sie pipe() aufrufen, müssen alle Zuweisungen an res.setHeader oder res.statusCode vor dem Aufruf von pipe() erfolgen. Ein gängiges Muster besteht darin, im onShellReady-Callback den Status 200 und Content-Type: text/html zu setzen und direkt danach pipe(res) aufzurufen.

onShellError wird ausgelöst, wenn ein nicht behebbarer Fehler auftritt, bevor die Shell vollständig gerendert ist — beispielsweise wenn eine Komponente auf oberster Ebene außerhalb einer Suspense-Boundary einen Fehler auslöst. In diesem Fall können Sie keine teilweise Antwort streamen. Leiten Sie stattdessen auf eine Fehlerseite um oder senden Sie ein statisches HTML-Fehlerdokument.

onAllReady wird ausgelöst, wenn der gesamte React-Baum aufgelöst wurde — einschließlich aller Suspense-Boundaries. Für Suchmaschinen-Crawler und Dienste, die Link-Vorschauen in sozialen Medien erzeugen, sollten Sie das vollständige HTML ohne Streaming senden. Prüfen Sie, ob die Anfrage von einem Bot stammt, und rufen Sie pipe(res) in onAllReady statt in onShellReady auf.

onError wird bei Fehlern innerhalb von Suspense-Boundaries ausgelöst — React kann den Rest der Seite weiterhin streamen, während diese Boundary auf ihre Fehler-UI zurückfällt. Verwenden Sie onError, um den Fehler in Ihrer Observability-Pipeline zu protokollieren, ohne den Stream für den Benutzer abzubrechen.

Wann sollten Sie statt onShellReady onAllReady verwenden, um das Streaming mit pipe zu starten?

renderToPipeableStream ist das Streaming-SSR-Primitive von React 18 für Node.js-Server. Es streamt die HTML-Shell sofort über onShellReady, ergänzt Suspense-Boundaries, sobald die Daten aufgelöst sind, und hydratisiert den Client über bootstrapScripts. Verwenden Sie onAllReady für Bots und Crawler, onShellError für fatale Fehler und setzen Sie HTTP-Header immer vor dem Aufruf von pipe().