Honoを使ったCloudflare Workers上のReact

Hono は、Cloudflare Workers、Deno Deploy、Bun、Node.js などのエッジランタイムで動作するように設計された、軽量で非常に高速な Web フレームワークです。API は Express に着想を得ていますが、Web 標準（Fetch API、Request/Response）を基盤として一から構築されているため、エッジ環境に自然に適合します。

Cloudflare Workers 用の新しい Hono プロジェクトのスキャフォールディングは簡単です。npm create hono@latest を実行するとテンプレートの選択が求められるので、"cloudflare-workers" を選択します。wrangler（Cloudflare の CLI）と Hono の依存関係があらかじめ設定されたプロジェクトが作成されます。

Hono Worker 内で React をサーバーレンダリングするには、react、react-dom、@types/react をインストールし、react-dom/server から renderToReadableStream をインポートします。この関数は React 18 のストリーミング API の一部で、Cloudflare Workers がサポートする Web Streams API に対応するよう設計されています。

一般的な SSR のルートハンドラーでは、ルート React コンポーネントを指定して renderToReadableStream を呼び出し、ストリームを await してから、c.body(stream, { headers: { 'Content-Type': 'text/html' } }) または c.html(htmlString) を使ってレスポンスを送信します。ストリームは HTML のチャンクを生成し、ブラウザーはそれを段階的にレンダリングできます。

renderToReadableStream は、HTML のチャンクを含む ReadableStream に解決される Promise を返します。この ReadableStream は Web Streams API に準拠しており、Response オブジェクトの body として直接渡せるため、Cloudflare Workers の fetch ハンドラーに適しています。

React のストリームが生成するのはコンポーネントツリーの HTML であり、周囲のドキュメントは含まれません。そのため、ストリームを HTML シェルに挿入する必要があります。HTML シェルは、doctype、meta タグと CSS link を含む head、開始 body タグ、React のストリーム、そして終了 body タグと html タグを含む文字列です。

Vite でビルドした React クライアントバンドルは、Worker と一緒に配信する必要があります。Cloudflare Pages または Workers Assets 機能を利用できます。c.env.ASSETS.fetch(request) によってアセットのリクエスト（JS、CSS、画像）がルーティングされ、Worker のデプロイ時にアップロードされた静的ファイルが返されます。

Worker のエントリーファイルは、fetch ハンドラーを持つデフォルトオブジェクトをエクスポートします。export default { fetch: app.fetch } のように記述します。Hono の app.fetch メソッドは、Request を受け取って Response を返す互換性のある fetch ハンドラーなので、Workers ランタイムに直接接続できます。

wrangler dev は、Cloudflare Workers ランタイムをマシン上でエミュレートするローカル開発サーバーを起動します。ファイルの変更を監視して自動的に再読み込みするため、本番環境にデプロイする前に高速なローカル開発ループを実現できます。

wrangler deploy は Worker のコードをバンドルして Cloudflare のネットワークにアップロードし、数秒以内に 300 か所以上のすべてのエッジロケーションで利用できるようにします。wrangler.toml 設定ファイルでは、アカウント ID、Worker 名、KV namespace や D1 database のバインディングを指定します。

クライアント側のインタラクティブ性を有効にするには、renderToReadableStream に bootstrapScripts: ['/assets/client.js'] を渡します。React は、クライアントバンドルを読み込んでサーバーレンダリング済みの DOM に対して hydrateRoot を呼び出す script タグを HTML に挿入します。これにより、JS の読み込み後にページがインタラクティブになります。

renderToReadableStream は何を返しますか？

Hono は、React の renderToReadableStream ときれいに統合できる、軽量でエッジネイティブな HTTP フレームワークです。Worker のエントリーポイントは app.fetch を Workers ランタイムに直接エクスポートし、静的アセットは ASSETS バインディング経由で配信します。wrangler はローカル開発と本番デプロイの両方を処理します。bootstrapScripts によって、ストリーミングされた HTML とクライアント側のハイドレーションバンドルが接続されます。