Strumieniowanie w React 18: jak działa renderToPipeableStream

Przed React 18 renderowanie po stronie serwera korzystało z renderToString, które działa synchronicznie: React renderuje całe drzewo komponentów do postaci ciągu znaków, zanim wyśle jakikolwiek kod HTML do przeglądarki. Jeśli którykolwiek komponent ładuje dane, serwer musi czekać na wszystkie dane, zanim pierwszy bajt dotrze do użytkownika.

React 18 wprowadził renderToPipeableStream, który renderuje drzewo komponentów jako strumień fragmentów HTML. Zamiast czekać na przygotowanie całości, React wysyła HTML w miarę ukończenia poszczególnych części drzewa, dzięki czemu przeglądarka może natychmiast rozpocząć renderowanie widocznej zawartości.

renderToPipeableStream zwraca obiekt z dwiema metodami: pipe(writable) i abort(). Metoda pipe przyjmuje strumień zapisywalny Node.js (zwykle odpowiedź HTTP) i rozpoczyna strumieniowe przesyłanie do niego kodu HTML. Metoda abort() anuluje strumień; używa się jej po anulowaniu żądania lub przekroczeniu limitu czasu.

Strumień rozpoczyna się od powłoki HTML — całej zawartości, której nie blokuje oczekująca granica Suspense. Obejmuje ona sekcję head dokumentu, nawigację, stopkę, elementy układu oraz wszelką zawartość dostępną synchronicznie. Shell jest przesyłany natychmiast, zanim komponenty zależne od danych zostaną rozstrzygnięte.

Komponenty znajdujące się wewnątrz granic Suspense i oczekujące na dane są początkowo przesyłane jako ich zastępczy interfejs użytkownika (np. wskaźnik ładowania). React wysyła później tag skryptu, który zastępuje wartość zastępczą rozstrzygniętą zawartością — wszystko to bez ponownego renderowania shellu po stronie klienta.

Przekazanie bootstrapScripts: ['/static/js/client.js'] do renderToPipeableStream informuje React, aby wstawił tag skryptu na końcu strumienia. Przeglądarka ładuje ten bundle i wywołuje hydrateRoot, dołączając handlery zdarzeń Reacta do DOM wyrenderowanego przez serwer.

onShellReady jest wywoływany, gdy shell HTML (wszystko poza oczekującymi granicami Suspense) jest gotowy do wysłania. To właściwy moment na wywołanie pipe(res) — należy jednak pamiętać, aby przed wywołaniem pipe ustawić kod statusu HTTP i nagłówki odpowiedzi, ponieważ strumieniowanie utrwala status HTTP.

Ponieważ strumieniowanie rozpoczyna się natychmiast po wywołaniu pipe(), wszystkie przypisania do res.setHeader lub res.statusCode muszą nastąpić przed wywołaniem pipe. Często stosowany wzorzec polega na ustawieniu statusu 200 i Content-Type: text/html w wywołaniu zwrotnym onShellReady, a następnie natychmiastowym wywołaniu pipe(res).

onShellError jest wywoływane, gdy przed ukończeniem renderowania powłoki wystąpi nieodwracalny błąd — na przykład gdy komponent najwyższego poziomu zgłosi wyjątek poza granicami Suspense. W takiej sytuacji nie można strumieniować częściowej odpowiedzi; zamiast tego należy przekierować użytkownika na stronę błędu lub wysłać statyczny dokument HTML z błędem.

onAllReady jest wywoływane, gdy w całym drzewie Reacta zakończy się rozwiązywanie danych — w tym we wszystkich granicach Suspense. W przypadku robotów indeksujących wyszukiwarek i narzędzi generujących podglądy linków w mediach społecznościowych należy wysłać kompletny dokument HTML bez strumieniowania. Należy sprawdzić, czy żądanie pochodzi od bota, i wywołać pipe(res) w onAllReady zamiast w onShellReady.

onError jest wywoływane w przypadku błędów w granicach Suspense — React może nadal strumieniować pozostałą część strony, podczas gdy ta granica przechodzi do swojego interfejsu błędu. Należy użyć onError do zarejestrowania błędu w potoku observability bez przerywania strumienia dla użytkownika.

Kiedy należy użyć onAllReady zamiast onShellReady, aby rozpocząć strumieniowanie za pomocą pipe?

renderToPipeableStream to mechanizm strumieniowego SSR w React 18 przeznaczony dla serwerów Node.js. Strumieniuje powłokę HTML natychmiast za pomocą onShellReady, uzupełnia granice Suspense w miarę rozwiązywania danych i nawodnia klienta za pomocą bootstrapScripts. Należy używać onAllReady w przypadku botów i robotów indeksujących, onShellError w przypadku krytycznych awarii oraz zawsze ustawiać nagłówki HTTP przed wywołaniem pipe().