Потоковая передача в React 18: как работает renderToPipeableStream

До React 18 серверная отрисовка использовала renderToString, работающий синхронно: React полностью преобразовывал дерево компонентов в строку до отправки любого HTML в браузер. Если какой-либо компонент загружал данные, серверу приходилось ждать все данные, прежде чем первый байт достигал пользователя.

В React 18 появился renderToPipeableStream, который преобразует дерево компонентов в поток фрагментов HTML. Вместо ожидания полной готовности React отправляет HTML по мере завершения каждой части дерева, позволяя браузеру немедленно начать отрисовку видимого содержимого.

renderToPipeableStream возвращает объект с двумя методами: pipe(writable) и abort(). Метод pipe принимает доступный для записи поток Node.js Writable, обычно HTTP-ответ, и начинает передавать в него HTML. abort() отменяет поток, когда запрос отменён или превышено время ожидания.

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

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

Передайте bootstrapScripts: ['/static/js/client.js'] в renderToPipeableStream, чтобы указать React вставить тег script в конец потока. Браузер загружает этот пакет и вызывает hydrateRoot, подключая обработчики событий React к отрисованному сервером DOM.

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

Поскольку потоковая передача начинается сразу после вызова pipe(), все присваивания res.setHeader или res.statusCode должны выполняться до вызова pipe(). Распространённый шаблон — установить статус 200 и Content-Type: text/html в обратном вызове onShellReady, а сразу после этого вызвать pipe(res).

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

onAllReady срабатывает, когда всё дерево React полностью разрешено, включая все границы Suspense. Для поисковых роботов и средств предварительного просмотра ссылок в социальных сетях необходимо отправлять полный HTML без потоковой передачи. Проверьте, что запрос поступил от бота, и вызовите pipe(res) в onAllReady вместо onShellReady.

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

Когда следует использовать onAllReady вместо onShellReady для начала передачи?

renderToPipeableStream — это примитив потоковой SSR в React 18 для серверов Node.js. Он немедленно передаёт HTML-оболочку через onShellReady, заполняет границы Suspense по мере разрешения данных и гидратирует клиент с помощью bootstrapScripts. Используйте onAllReady для ботов и поисковых роботов, onShellError — для критических сбоев и всегда устанавливайте HTTP-заголовки до вызова pipe().