Cloudflare WorkersでReactを動かす！静的サイトからSSRまで環境構築完全ガイド

### 主題と目的 この調査の主題は、Cloudflare Workersを利用してReactやHTMLで構築されたウェブアプリケーションの実行環境を構築する方法です。目的は、最も基本的な静的サイトのホスティングから、サーバーサイドレンダリング（SSR）のような高度な環境構築、さらには開発ワークフローの効率化やパフォーマンス最適化に至るまで、包括的かつ実践的な手順と知識を提供することです。これにより、開発者は自身のプロジェクト要件に最適なアプローチを選択し、Cloudflare Workersの能力を最大限に活用できるようになることを目指します。 ### 回答 #### Cloudflare Workersでウェブアプリを実行する魅力 Cloudflare Workersは、単なるサーバーレス関数プラットフォームから、高機能なウェブアプリケーション実行環境へと進化を遂げています。特筆すべきは、Cloudflare自身が新規プロジェクトにおいて、従来の静的ホスティングサービス「Cloudflare Pages」よりもWorkersの利用を推奨する方針を打ち出している点です[2](https://zenn.dev/aya_koto/articles/ccb42aa50fc973)。これは、Workersが持つ圧倒的な柔軟性、拡張性、そしてCloudflareの他のサービスとの統合性の高さが、現代のウェブ開発に不可欠であると認識されていることを示しています。 本稿では、ReactやHTMLサイトをWorkers上で実行するための環境構築方法を、3つのステップに分けて具体的に解説します。 #### ステップ1：基本の静的サイトホスティング 最も手軽で一般的な方法が、ビルド済みの静的なHTML、CSS、JSファイルをホスティングする「Workers Sites」です。JAMstackアーキテクチャ[11](https://qiita.com/to-yoshiki/items/7374afe90df0fcc31dcc)と非常に相性が良く、ブログやコーポレートサイトに最適です。 ##### 必要な準備 開発を始める前に、以下のツールを準備してください。 1. **Cloudflareアカウント**: [公式サイト](https://dash.cloudflare.com/sign-up/workers-and-pages)から無料でサインアップします[3](https://developers.cloudflare.com/workers/get-started/guide/)。 2. **Node.js**: バージョン16.17.0以降をインストールします[3](https://developers.cloudflare.com/workers/get-started/guide/)。 3. **Wrangler CLI**: Cloudflare Workers用のコマンドラインツールです。以下のコマンドでインストールします[4](https://www.howtogeek.com/devops/how-to-use-cloudflare-workers-and-kv-to-serve-a-static-site/)。 ```bash npm install -g @cloudflare/wrangler ``` ##### 構築手順（パターン別） - **パターン1: React製SPA（シングルページアプリケーション）をホストする** 最も簡単な方法は、Cloudflareが提供する公式テンプレートを利用することです[5](https://developers.cloudflare.com/workers/static-assets/)。 ```bash npm create cloudflare@latest my-react-app -- --framework=react ``` 既存のプロジェクトがある場合は、`wrangler.toml`ファイルに以下の設定を追加します。`not_found_handling`の設定により、React Routerなどのクライアントサイドルーティングが正しく機能します[5](https://developers.cloudflare.com/workers/static-assets/)。 ```toml # wrangler.toml name = "my-react-spa" compatibility_date = "2025-01-01" [assets] directory = "./build" # Reactアプリのビルド出力ディレクトリ not_found_handling = "single-page-application" ``` - **パターン2: シンプルなHTMLサイトをホストする** 素のHTML、CSS、JavaScriptで構成されたサイトの場合、`wrangler.jsonc`ファイルを作成し、アセットのディレクトリを指定するだけで設定は完了です[2](https://zenn.dev/aya_koto/articles/ccb42aa50fc973)。 ```json // wrangler.jsonc { "name": "my-static-site", "compatibility_date": "2025-05-06", "assets": { "directory": "./" } } ``` ##### ローカル確認とデプロイ 1. **ローカルプレビュー**: `npx wrangler dev` を実行し、ローカルサーバーで動作を確認します[3](https://developers.cloudflare.com/workers/get-started/guide/)。 2. **デプロイ**: `npx wrangler deploy` を実行し、サイトをCloudflareのグローバルネットワークに公開します[3](https://developers.cloudflare.com/workers/get-started/guide/)。 #### ステップ2：動的要素の導入と高度なレンダリング 静的サイトの高速性を維持しつつ、よりリッチでインタラクティブな体験を提供するための高度な手法を紹介します。 ##### 選択肢1: `HTMLRewriter`によるエッジでの動的書き換え `HTMLRewriter`は、オリジンサーバーから返されたHTMLや静的HTMLを、エッジ（ユーザーに最も近いサーバー）でストリーミングしながら書き換えるCloudflare Workers独自の強力なAPIです[12]。 - **仕組み**: CSSセレクタでHTML要素をターゲットにし、内容や属性を動的に変更します。 - **メリット**: クライアントサイドのJavaScriptに頼ることなく、パーソナライズ（例：ログイン状態の表示切替）やA/Bテストを、パフォーマンスへの影響を最小限に抑えて実現できます。レンダリングブロックや表示の「ちらつき」も防げます[12]。 ##### 選択肢2: サーバーサイドレンダリング (SSR) 初期表示速度の向上やSEO対策が重要なアプリケーションではSSRが不可欠です。モダンなツールを組み合わせることで、Workers上で本格的なSSR環境を構築できます。 | ツール / フレームワーク | 特徴 | 最適な用途 | |---|---|---| | **React Router (旧Remix)** | Cloudflareが公式にサポートするフルスタックフレームワーク。`create-cloudflare` CLIで簡単に環境を構築可能[1](https://developers.cloudflare.com/workers/frameworks/remix/)。 | 安定した公式サポートとCloudflareのエコシステムを最大限に活用したい本格的なアプリケーション。 | | **Hono + Vite** | 軽量で柔軟なWebフレームワークHono[8]と高速ビルドツールViteの組み合わせ。ほぼ「素のReact」に近い感覚でSSRを構築可能[0](https://zenn.dev/sora_kumo/articles/hono-ssr-react)。 | フレームワークの規約に縛られず、独自の構成で軽量なSSR環境を構築したい場合。 | | **vite-plugin-ssr** | SSRだけでなく静的サイト生成(SSG)もサポートする汎用的なViteプラグイン。Next.jsは大規模すぎると感じる場合に最適[3](https://zenn.dev/aiji42/scraps/9c8aa88de3d38a)。 | Next.jsの複雑さを避けつつ、SSR/SSGやファイルベースルーティングなどモダンな機能を使いたい場合。 | #### ステップ3：開発効率とパフォーマンスの最大化 環境構築後の運用フェーズでは、開発効率とアプリケーション性能を高めるためのテクニックが重要になります。 ##### 効率的なデバッグ - **ローカル開発**: `wrangler dev`コマンドでローカルサーバーを起動し、即座にコードの変更をテストできます[65](https://developers.cloudflare.com/workers/development-testing/)。 - **DevTools連携**: `wrangler dev`の実行中にターミナルで`D`キーを押すだけでChrome DevToolsが起動し、コンソールログの確認やパフォーマンスのプロファイリングが可能です[64](https://developers.cloudflare.com/workers/observability/dev-tools/)。 - **ブレークポイント**: VS Codeに特定の設定[66](https://developers.cloudflare.com/workers/observability/dev-tools/breakpoints/)を追加することで、ブレークポイントを使った高度なデバッグが実現します。 ##### CI/CDによるデプロイ自動化 GitHub ActionsとCloudflare公式の`wrangler-action`[1](https://github.com/marketplace/actions/deploy-to-cloudflare-workers-with-wrangler)を組み合わせることで、デプロイの完全自動化が可能です。 - **認証情報**: CloudflareのAPIトークンとアカウントIDは、GitHubリポジトリのSecrets機能を使って安全に管理します[0](https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/)。 - **機密情報管理**: 機密情報を含む`wrangler.toml`ファイルはリポジトリに含めず、その内容全体をGitHub Secretsに保存し、ワークフロー実行時に動的にファイルを生成するアプローチが安全かつ効果的です[4](https://zenn.dev/makura_nageru/articles/1ec67bf3bc2a0d)。 ##### パフォーマンス最適化 - **キャッシュ戦略**: 動的に生成されたHTMLをキャッシュすることで、応答速度を劇的に改善できます。 | キャッシュ方法 | 特徴 | 推奨ユースケース | |---|---|---| | **Cache API** | Workerが実行されたデータセンターにのみキャッシュを保存。高速だがグローバルな一貫性はない[6](https://zenn.dev/chimame/articles/7570c71d1e6c38)。 | 高速なレスポンスが最優先で、グローバルでの一貫性が厳密には不要な場合。 | | **Workers KV** | グローバルに分散されたKVS。世界中のどこからでも高速に読み取れる[9](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/caching/)。 | 高いキャッシュヒット率やグローバルな状態共有が求められる場合。Next.jsのISRなどで推奨[9](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/caching/)。 | - **バンドルサイズ最適化**: Cloudflare Pagesのファイルサイズ上限（25MiB）[14](https://blog.developersteve.com/overcoming-the-cloudflare-asset-file-limit-using-github-actions-145a87215004)などを回避するため、バンドルサイズを小さく保つことが重要です。ビルドプロセスをGitHub Actions上で行い、生成された静的ファイルのみをデプロイする手法が有効です[14](https://blog.developersteve.com/overcoming-the-cloudflare-asset-file-limit-using-github-actions-145a87215004)。 ### 結果と結論 調査の結果、Cloudflare Workersは、単純な静的サイトホスティングから、`HTMLRewriter`による動的なHTML書き換え、さらにはReact RouterやHonoを用いた本格的なサーバーサイドレンダリング（SSR）まで、非常に多様なウェブアプリケーションの実行環境を構築できる、柔軟で強力なプラットフォームであることが明らかになりました。 結論として、Cloudflare Workersは現代のウェブ開発において極めて魅力的な選択肢です。プロジェクトの要件に応じて、シンプルな静的ホスティングから始め、必要に応じてSSRへと段階的に進化させることができます。Wrangler CLIやViteプラグイン、DevTools連携といった充実した開発者ツールは優れた開発体験を提供し、CI/CDの導入や高度なキャッシュ戦略、バンドルサイズ最適化といった実践的なテクニックを組み合わせることで、スケーラブルで高性能、かつ運用性に優れたアプリケーションの構築が可能です。この柔軟性と拡張性こそが、Cloudflare Workersを際立たせる最大の強みと言えるでしょう。

### 調査の本質：単なる技術手順を超えた、最適なアーキテクチャ選定への道標 ユーザーの皆様からの「Cloudflare WorkersでReactやHTMLのコードを実行できる環境を作る方法」というご依頼は、単に技術的な手順を求めるものではありません。その根底には、「**現代のウェブ開発において、高速でスケーラブル、かつコスト効率の良いアプリケーションを構築するための最適なプラットフォームは何か？**」という、より本質的で戦略的な問いが存在します。 したがって、私たちが提供すべき価値は、手順の羅列にとどまらず、プロジェクトの性質や将来の成長を見据え、**なぜCloudflare Workersが有力な選択肢となり得るのか**、そして**どのような状況で、どのアーキテクチャ（静的サイト、動的HTML、SSR）を選択すべきか**という明確な意思決定の指針を示すことです。 本考察の目的は、調査結果を深く分析し、技術的な選択がビジネスやプロジェクトの成功にどう結びつくのかを解き明かし、皆様が自信を持って次のステップに進むための具体的な洞察とアクションプランを提供することにあります。 ### 分析と発見事項：エッジコンピューティングへのパラダイムシフト 調査結果を多角的に分析すると、いくつかの重要な発見と、ウェブ開発における大きなトレンドが見えてきます。 #### 発見事項1：静的ホスティングからプログラマブルなエッジへの主役交代 最も注目すべきは、Cloudflare自身が新規プロジェクトにおいて、従来の静的ホスティングサービス`Cloudflare Pages`よりも、サーバーレス環境である`Cloudflare Workers`の利用を推奨しているという事実です[2](https://zenn.dev/aya_koto/articles/ccb42aa50fc973)。これは、ウェブホスティングのパラダイムが、単にファイルを配置する「静的」なモデルから、エッジサーバーでコードを実行する「動的・プログラマブル」なモデルへと移行していることを明確に示しています。Workersは静的アセットのホスティング機能を内包しつつ、APIの構築や動的な処理など、はるかに高い柔軟性と拡張性を提供します。 #### 発見事項2：3つの実行パターンが示す「スケーラブルな進化の道筋」 Cloudflare WorkersでのReact/HTML実行方法は、大きく3つのパターンに分類できます。これらは単なる選択肢ではなく、プロジェクトの成長に合わせて進化できる、一連の道筋として捉えることができます。 | 実行パターン | 特徴 | 最適なユースケース | |---|---|---| | **1. 静的サイトホスティング** | 最もシンプルで高速。ビルド済みのHTML/CSS/JSを配信。 | ブログ、ポートフォリオ、コーポレートサイト、ドキュメント | | **2. `HTMLRewriter`による動的挿入** | 静的サイトの速度を維持しつつ、エッジでHTMLを部分的に書き換え。 | ユーザー認証による表示切り替え、A/Bテスト、地域別コンテンツ | | **3. サーバーサイドレンダリング (SSR)** | エッジでReactをレンダリングし、SEOと初期表示速度を最大化。 | Eコマースサイト、メディアサイト、複雑なWebアプリケーション | この段階的なアプローチは、初期段階ではシンプルかつ低コストで始め、ビジネスの成長や機能要件の高度化に伴って、シームレスにより高度なアーキテクチャへ移行できることを意味します。 #### 発見事項3：開発者体験（DX）を重視したエコシステムの成熟 調査結果からは、Cloudflareが本番運用だけでなく、開発プロセス全体の効率化を重視していることが伺えます。 - **ローカルデバッグ**: `wrangler dev`とブラウザのDevToolsを連携させ、ブレークポイントデバッグまで可能な環境が提供されています[64](https://developers.cloudflare.com/workers/observability/dev-tools/)[66](https://developers.cloudflare.com/workers/observability/dev-tools/breakpoints/)。 - **CI/CDの自動化**: GitHub Actionsとの公式連携により、安全かつ自動化されたデプロイパイプラインの構築が容易になっています[0](https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/)。 - **モダンツールとの連携**: Vite[5]やHono[8]、Remix[1]といった現代の開発者に人気のツールとの親和性が高く、スムーズな開発体験を実現しています。 これらの発見は、Cloudflare Workersがもはや実験的なプラットフォームではなく、本格的なアプリケーション開発のための成熟したエコシステムを形成していることを示しています。 ### より深い分析と解釈：「なぜ」を掘り下げて本質を探る 表面的な事実の背後にある「なぜ」を掘り下げることで、より本質的な意味を解き明かします。 #### なぜCloudflareは静的サイトにまで「Workers」を推奨するのか？ これは、Cloudflareが開発者を自社の**エコシステムに深く取り込むための戦略**と解釈できます。 1. **初期接点の獲得**: まずは最も手軽な静的サイトホスティングで開発者を呼び込みます。 2. **シームレスな拡張**: プロジェクトが成長し、動的な機能（例: データベース接続、認証）が必要になった際、開発者はプラットフォームを乗り換える必要がありません。Workersを基盤として、KV（KVS）、D1（SQLデータベース）、Durable Objects（ステートフル）といったCloudflareの他のサービスを簡単に追加できます。 3. **将来性の提示**: 「今は静的サイトでも、将来的にはフルスタックアプリにまで成長できる」という安心感と拡張性を提供することで、VercelやNetlifyといった競合に対する強力な差別化要因としています。 つまり、`Workers`の推奨は、単なる技術的な優位性だけでなく、開発者のライフサイクル全体をサポートするというビジネス戦略の現れなのです。 #### なぜ「HTMLRewriter」はゲームチェンジャーとなり得るのか？ `HTMLRewriter`の価値は、**静的サイトと動的サイトの「良いとこ取り」を実現する点**にあります。 1. **パフォーマンスの維持**: 従来の動的サイトは、サーバーでの処理待ちがボトルネックになりがちでした。`HTMLRewriter`は、キャッシュされた静的HTMLをベースに、ユーザーに最も近いエッジで瞬時に変更を加えるため、体感速度をほとんど損ないません。 2. **Core Web Vitalsへの貢献**: クライアントサイドJavaScriptでDOMを操作する場合に発生しがちな「表示のちらつき（レイアウトシフト）」を防ぎ、Googleが重視するユーザー体験指標上有利になります。 3. **アーキテクチャの簡素化**: A/Bテストやパーソナライゼーションのために、複雑なバックエンドロジックやクライアントサイドの状態管理を構築する必要がなくなります。これにより、開発と運用のコストを大幅に削減できる可能性があります。 `HTMLRewriter`は、これまでトレードオフの関係にあった「速度」と「動的機能」を両立させる、エッジコンピューティングならではの革新的なソリューションと言えます。 ### 戦略的示唆：プロジェクトを成功に導くための実践的アクションプラン これらの分析と解釈から、皆様が取るべき具体的なアクションを提案します。 #### 提案1：プロジェクト要件に基づくアーキテクチャ選定フレームワーク 技術選定で迷わないために、以下のフレームワークでプロジェクトの要件を整理し、最適な実行パターンを選択してください。 ```mermaid graph TD A[プロジェクト開始] --> B{動的な要素は必要？}; B -- No --> C[パターン1: 静的サイトホスティング]; B -- Yes --> D{SEO/初期表示速度が最重要？}; D -- No --> E{動的要素は部分的？}; E -- Yes --> F[パターン2: HTMLRewriter]; E -- No --> G[パターン3: SSR]; D -- Yes --> G[パターン3: SSR]; subgraph "推奨アクション" C["最もシンプル＆高速<br>ブログ、ドキュメントに最適"] F["静的サイトの速度 + 動的機能<br>パーソナライゼーションに最適"] G["最高のパフォーマンスとSEO<br>Eコマース、メディアサイトに最適"] end ``` #### 提案2：段階的進化（Progressive Enhancement）戦略の採用 「最初から完璧なSSR環境を構築しなければ」と考える必要はありません。以下の段階的アプローチを推奨します。 1. **Phase 1: Start Simple (MVP)** - まずは**静的サイトホスティング**で迅速にサービスを立ち上げます。`create-cloudflare`コマンドを使えば数分で完了します[5](https://developers.cloudflare.com/workers/static-assets/)。同時に、GitHub ActionsによるCI/CDパイプラインを構築し、開発の基盤を固めます[0](https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/)。 2. **Phase 2: Add Dynamics (機能拡張)** - ユーザー認証やA/Bテストといった動的機能が必要になったら、**`HTMLRewriter`**を導入します。既存の静的サイトの構成を大きく変えることなく、低リスクで機能を追加できます。 3. **Phase 3: Go Full-Stack (スケールアップ)** - ビジネスが拡大し、より高度なインタラクティビティやSEO対策が求められるようになった時点で、**SSRへの移行**を検討します。この段階では、Remix[1]やHono[0]といったフレームワークの導入が視野に入ります。キャッシュ戦略（Cache APIやKV[9](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/caching/)）を組み合わせることで、パフォーマンスを最大化します。 この戦略により、初期投資を抑えつつ、将来のスケールアップにも柔軟に対応できる技術的負債の少ない開発が可能になります。 ### 今後の調査：継続的な改善と未来への展望 今回の分析を一過性のものとせず、継続的な改善につなげるために、以下のテーマについて追加調査を行うことを推奨します。 - **実践的なパフォーマンスベンチマーク**: - 静的サイト、`HTMLRewriter`利用時、SSR利用時のTTFB（Time to First Byte）およびLCP（Largest Contentful Paint）を実測し、定量的に比較評価する。 - Cache APIとWorkers KVをキャッシュバックエンドとして使用した場合の、レスポンスタイムとグローバルな伝播速度の違いを検証する。 - **コスト対効果の分析**: - 各アーキテクチャ（静的、SSRなど）における、トラフィック量に応じたCloudflareの利用料金をシミュレーションし、TCO（総所有コスト）を比較する。 - **競合プラットフォームとの比較分析**: - Vercel、Netlify、AWS Amplifyといった主要な競合サービスと、Cloudflare Workersを「開発者体験」「パフォーマンス」「料金体系」「エコシステムの拡張性」の4つの軸で詳細に比較する。 - **セキュリティアーキテクチャの検討**: - SSRや`HTMLRewriter`を導入する際に考慮すべき具体的なセキュリティ脅威（例：XSS、CSRF、機密情報の漏洩）と、Cloudflareの機能を活用した緩和策を調査・整理する。