Потоковая SSR с периферии

Когда сервер передаёт HTML потоково, браузер получает и отображает контент фрагментами, не дожидаясь полного документа. Пользователи могут видеть и использовать уже отображённые части страницы — шапку, навигацию и главный экран, — пока более медленные разделы, зависящие от данных, ещё загружаются.

Передача bootstrapScripts в renderToReadableStream сообщает React, где находится клиентский пакет JS. React добавляет тег script в конце потока, чтобы браузер загрузил пакет и вызвал hydrateRoot, делая страницу интерактивной по мере потоковой передачи каждого раздела.

Потоковая передача в React опирается на границы Suspense, разделяющие дерево компонентов на независимо передаваемые потоком разделы. Компоненты внутри границы Suspense, ожидающие данные (через выброшенный Promise), сначала передаются как заполнители, а затем разрешаются и позже передают своё настоящее содержимое.

Обратный вызов onShellReady срабатывает, когда HTML-оболочка без приостановленных частей — всё, что находится за пределами границ Suspense, — готова к потоковой передаче. Это подходящий момент, чтобы установить код состояния HTTP и заголовки ответа, а затем вызвать pipe(res) или начать чтение из ReadableStream.

Коды состояния HTTP и заголовки необходимо отправить до начала передачи тела ответа. Поскольку потоковая передача начинается с onShellReady, вся логика обработки ошибок — установка состояния 500 или перенаправление — должна выполняться до начала передачи оболочки: после начала потоковой передачи код состояния уже нельзя изменить.

onShellError срабатывает, когда до готовности оболочки происходит критическая ошибка, например ошибка в корневом компоненте, находящемся за пределами любой границы Suspense. В этом случае оболочка не передаётся потоком, и следует ответить статической страницей ошибки или перенаправить пользователя на маршрут ошибки.

onError срабатывает для ошибок, которые можно обработать внутри границ Suspense. React всё ещё может передавать оставшуюся часть страницы; граница с ошибкой отображает резервный интерфейс ошибки. Используйте onError для ведения журнала: отправляйте сведения об ошибке на платформу наблюдаемости, не прерывая поток.

Если данные границы Suspense обрабатываются слишком долго, всё равно передайте оболочку в поток и позвольте границе гидратироваться на клиенте. Реализуйте тайм-аут: через 5 секунд вызовите abort() для потока, если граница ещё не разрешилась, и тогда клиент сам получит данные через useEffect.

Среда выполнения Workers напрямую передаёт ReadableStream как тело ответа. Инфраструктура Cloudflare пересылает каждый фрагмент в браузер пользователя по мере того, как React его формирует, не буферизуя весь документ. Это означает, что первые байты HTML покидают пограничный узел в течение нескольких миллисекунд после получения запроса.

renderToReadableStream возвращает функцию контроллера прерывания. Если запрос отменён (пользователь перешёл на другую страницу), вызов abort() останавливает дальнейшую отрисовку React и обработку данных. Это предотвращает напрасные вычисления для оставшихся без владельца запросов и ограничивает использование CPU рабочим процессом Worker.

При потоковой передаче с границы полная цепочка задержек выглядит так: 5 мс (от запроса до ближайшего пограничного узла) + 2 мс (холодный запуск Worker) + 8 мс (отрисовка оболочки) = 15 мс до получения первого байта. Браузер пользователя отрисовывает элемент LCP из оболочки, пока остальная часть страницы продолжает поступать в фоновом режиме.

Когда именно во время потоковой передачи SSR вызывается обратный вызов onShellReady?

Потоковая передача SSR с границы доставляет HTML фрагментами, улучшая FCP и LCP за счёт немедленной отправки оболочки. Границы Suspense разделяют дерево на независимые секции, которые можно передавать в потоке. onShellReady — это сигнал для начала передачи данных; коды состояния нужно задать до его вызова. onShellError обрабатывает критические сбои, onError — устранимые, а abort() предотвращает напрасную работу для отменённых запросов.