React 18のストリーミング：renderToPipeableStreamの仕組み

React 18 より前は、サーバーサイドレンダリングに同期的な renderToString が使用されていました。React はブラウザーに HTML を送信する前に、コンポーネントツリー全体を文字列にレンダリングします。いずれかのコンポーネントがデータを読み込む場合、最初のバイトがユーザーに届くまで、サーバーはすべてのデータを待たなければなりません。

React 18 では、コンポーネントツリーを HTML チャンクのストリームとしてレンダリングする renderToPipeableStream が導入されました。すべての準備が整うまで待つ代わりに、React はツリーの各部分の準備ができ次第 HTML を送信するため、ブラウザーは表示可能なコンテンツのレンダリングをすぐに開始できます。

renderToPipeableStream は、pipe(writable) と abort() という 2 つのメソッドを持つオブジェクトを返します。pipe は Node.js の Writable ストリーム（通常は HTTP レスポンス）を受け取り、そこへの HTML のストリーミングを開始します。abort() はストリームをキャンセルします。リクエストがキャンセルされた場合やタイムアウトを超過した場合に使用します。

ストリームは HTML シェルから始まります。これは、保留中の Suspense 境界によってブロックされていないすべてのコンテンツです。ドキュメントの head、ナビゲーション、フッター、レイアウトの外枠、および同期的に利用可能なコンテンツが含まれます。シェルはデータに依存するコンポーネントが解決される前に、すぐにストリームされます。

データを待機している Suspense 境界内のコンポーネントは、最初はフォールバック UI（例：読み込みスピナー）としてストリームされます。その後 React は、フォールバックを解決済みのコンテンツに置き換える script タグを送信します。これらはすべて、クライアント側でシェルを再レンダリングすることなく行われます。

renderToPipeableStream に bootstrapScripts: ['/static/js/client.js'] を渡すと、ストリームの末尾に script タグを挿入するよう React に指示できます。ブラウザーはこのバンドルを読み込み、hydrateRoot を呼び出して、サーバーでレンダリングされた DOM に React のイベントハンドラーを関連付けます。

onShellReady は、HTML シェル（保留中の Suspense 境界の外側にあるすべての部分）の送信準備が整ったときに発火します。このタイミングで pipe(res) を呼び出すのが適切です。ただし重要なのは、ストリーミングによって HTTP ステータスが確定するため、pipe を呼び出す前に HTTP ステータスコードとレスポンスヘッダーを設定することです。

pipe() を呼び出すとストリーミングが直ちに始まるため、res.setHeader や res.statusCode の設定は pipe() を呼び出す前に行う必要があります。一般的なパターンは、onShellReady コールバックでステータスを 200、Content-Type を text/html に設定し、その直後に pipe(res) を呼び出す方法です。

onShellError は、シェルのレンダリングが完了する前に回復不能なエラーが発生すると呼び出されます。たとえば、Suspense 境界の外側にあるトップレベルのコンポーネントが例外をスローした場合です。この場合、レスポンスの一部をストリーミングすることはできないため、エラーページへリダイレクトするか、静的なエラー HTML ドキュメントを送信します。

onAllReady は、すべての Suspense 境界を含む React ツリー全体の解決が完了すると呼び出されます。検索エンジンのクローラーやソーシャルメディアのリンクプレビュー生成ツールには、ストリーミングせずに完全な HTML を送信します。リクエストがボットからのものかどうかを確認し、onShellReady ではなく onAllReady で pipe(res) を呼び出してください。

onError は Suspense 境界内のエラーに対して呼び出されます。React は、その境界がエラー UI にフォールバックしている間も、ページの残りの部分をストリーミングできます。onError を使ってエラーをオブザーバビリティパイプラインに記録し、ユーザー向けのストリームを中止しないようにしてください。

パイプ処理を開始する際、onShellReady ではなく onAllReady を使うのはどのような場合ですか？

renderToPipeableStream は、Node.js サーバー向けの React 18 のストリーミング SSR プリミティブです。onShellReady を介して HTML シェルを直ちにストリーミングし、データの解決に合わせて Suspense 境界を埋め、bootstrapScripts を使ってクライアントをハイドレーションします。ボットとクローラーには onAllReady を、致命的なエラーには onShellError を使い、必ず pipe() を呼び出す前に HTTP ヘッダーを設定してください。