Strumieniowanie SSR z brzegu sieci

Gdy serwer strumieniuje kod HTML, przeglądarka otrzymuje i renderuje treść we fragmentach, zamiast czekać na cały dokument. Dzięki temu użytkownicy mogą zobaczyć i używać widocznych części strony — nagłówka, nawigacji i sekcji hero — podczas gdy wolniejsze sekcje zależne od danych wciąż się ładują.

Przekazanie bootstrapScripts do renderToReadableStream informuje Reacta, gdzie znajduje się pakiet JavaScriptu po stronie klienta. React wstrzykuje znacznik script na końcu strumienia, aby przeglądarka załadowała pakiet i wywołała hydrateRoot, nadając stronie interaktywność w miarę strumieniowego przesyłania kolejnych sekcji.

Strumieniowanie Reacta opiera się na granicach Suspense, które dzielą drzewo komponentów na sekcje możliwe do niezależnego strumieniowania. Komponenty znajdujące się wewnątrz granicy Suspense i oczekujące na dane (za pośrednictwem rzuconego obiektu Promise) są najpierw strumieniowane jako zastępniki, a następnie po rozwiązaniu strumieniowana jest ich właściwa treść.

Funkcja callback onShellReady jest wywoływana, gdy powłoka HTML bez zawieszonych elementów — wszystko poza granicami Suspense — jest gotowa do strumieniowania. To właściwy moment na ustawienie kodu statusu HTTP i nagłówków odpowiedzi, a następnie wywołanie pipe(res) lub rozpoczęcie odczytu z ReadableStream.

Kody statusu HTTP i nagłówki muszą zostać wysłane przed rozpoczęciem przesyłania treści odpowiedzi. Ponieważ strumieniowanie rozpoczyna się w onShellReady, wszelkie czynności związane z obsługą błędów, takie jak ustawienie statusu 500 lub przekierowanie, muszą nastąpić przed rozpoczęciem przesyłania powłoki — po rozpoczęciu strumieniowania kod statusu jest już zablokowany.

onShellError jest wywoływane, gdy przed przygotowaniem powłoki wystąpi błąd krytyczny — na przykład błąd w komponencie najwyższego poziomu znajdującym się poza dowolną granicą Suspense. W takim przypadku powłoka nigdy nie jest strumieniowana i należy odpowiedzieć statyczną stroną błędu lub przekierować użytkownika do trasy błędu.

onError jest wywoływane w przypadku możliwych do odzyskania błędów wewnątrz granic Suspense. React nadal może strumieniować pozostałą część strony, a granica, w której wystąpił błąd, renderuje awaryjny interfejs użytkownika. Należy używać onError do rejestrowania błędów: przechwycić błąd w platformie obserwowalności bez przerywania strumienia.

Jeśli dane granicy Suspense są pobierane zbyt długo, należy mimo to przesłać szkielet i pozwolić, aby granica została zhydratowana po stronie klienta. Należy zaimplementować limit czasu: po 5 sekundach wywołać abort() dla strumienia, jeśli granica nie zostanie rozwiązana, a klient sam pobierze dane za pośrednictwem useEffect.

Środowisko uruchomieniowe Workers przekazuje ReadableStream bezpośrednio jako treść Response. Infrastruktura Cloudflare przekazuje każdy fragment do przeglądarki użytkownika w miarę generowania go przez React, bez buforowania całego dokumentu. Oznacza to, że pierwsze bajty HTML opuszczają brzegowy PoP w ciągu milisekund od nadejścia żądania.

renderToReadableStream zwraca funkcję kontrolującą przerwanie. Jeśli żądanie zostanie anulowane (użytkownik przejdzie na inną stronę), wywołanie abort() zatrzymuje React przed dalszym renderowaniem i przetwarzaniem danych. Zapobiega to marnowaniu zasobów obliczeniowych na osierocone żądania i ogranicza zużycie CPU Workera.

W przypadku strumieniowania na brzegu pełny łańcuch opóźnień wygląda następująco: 5 ms (żądanie do najbliższego PoP) + 2 ms (zimny start Workera) + 8 ms (renderowanie szkieletu) = 15 ms do pierwszego bajtu. Przeglądarka użytkownika renderuje element LCP ze szkieletu, podczas gdy reszta strony nadal jest przesyłana strumieniowo w tle.

Kiedy dokładnie podczas strumieniowego SSR jest wywoływany callback onShellReady?

Strumieniowe SSR z brzegu dostarcza HTML we fragmentach, poprawiając FCP i LCP dzięki natychmiastowemu wysłaniu szkieletu. Granice Suspense dzielą drzewo na niezależnie przesyłane strumieniowo sekcje. onShellReady to sygnał do rozpoczęcia przekazywania strumienia — kody statusu należy ustawić przed jego wywołaniem. onShellError obsługuje błędy krytyczne, onError — błędy możliwe do odzyskania, a abort() zapobiega marnowaniu pracy po anulowaniu żądania.