この記事では、Ionic フレームワークで作成した React アプリを Cloudflare へデプロイする方法について紹介します。Pages ではなく Workers をつかう新しい方法と、後半では少しだけ REST API を同時にホストする方法についても解説します。

Ionic React アプリの開発とビルド

まず、Ionic を使って React プロジェクトを作成しましょう。以下のコマンドでプロジェクトを開始し、フレームワークとして React を選択します。

ionic start
# ウィザードを使用するか尋ねられたら「No」を選択
# フレームワーク選択で「React」を選択

プロジェクトが作成されたら、通常の開発ワークフローでアプリを開発していきます。React Router などを使ってルーティングを設定し、必要な機能を実装していく流れになります。

ビルドの実行

デプロイする前に、アプリをビルドして静的ファイルを生成する必要があります。

npm run build

ビルドが成功すると、dist ディレクトリにアプリケーションの静的ファイルが生成されます。これには、HTML、CSS、JavaScript ファイル、アセットなどが含まれています。

dist/assets/status-tap-legacy-Djz6pJPx.js        0.60 kB
dist/assets/focus-visible-legacy-CdO5cX4I.js     1.09 kB
dist/assets/md.transition-legacy-Ccej1VZc.js     1.13 kB
...
dist/index.html                                   2.33 kB
dist/assets/index-DKlQdGq3.css                   29.60 kB
...
dist/assets/index-Cla2GAsa.js                   409.97 kB

このディレクトリが Cloudflare Workers にデプロイするコンテンツとなります。

Cloudflare Workers の基本設定

Cloudflare Workers へのデプロイには Wrangler を使用します。以下のコマンドでプロジェクトに Wrangler をインストールしてください。

npm i -D wrangler

wrangler.json の作成

プロジェクトのルートディレクトリに wrangler.json ファイルを作成し、Cloudflare Workers の設定を記述します。

{
  "name": "my-spa",
  "compatibility_date": "2025-04-01",
  "assets": {
    "directory": "./dist"
  }
}

この設定では、name が Workers プロジェクトの名前、compatibility_date が Workers の互換性日付、assets.directory が静的ファイルのディレクトリパスを指定しています。

デプロイコマンドの設定

package.json ファイルにデプロイコマンドを追加します。

"scripts": {
  "start": "ionic serve",
  "build": "tsc && vite build",
  "preview": "vite preview",
  "test.e2e": "cypress run",
  "test.unit": "vitest",
  "lint": "eslint",
+ "deploy": "npm run build && npx wrangler deploy"
},

これにより、npm run deploy コマンドでビルドとデプロイを一度に実行できるようになります。

Cloudflare Workers での SPA のルーティングについて

SPA（シングルページアプリケーション）では、クライアントサイドのルーティングを使用するため、サーバーサイドでもそれに対応した設定が必要です。React Router などを使用している場合、ルートパス以外のパスに直接アクセスすると 404 エラーが発生してしまう問題があります。

SPA 対応の設定

Cloudflare Workers でこの問題を解決するには、wrangler.json の assets 設定に not_found_handling オプションを追加します。

{
  "name": "my-spa",
  "compatibility_date": "2025-04-01",
  "assets": {
    "directory": "./dist",
    "not_found_handling": "single-page-application"
  }
}

not_found_handling: "single-page-application" を設定することで、静的ファイルが見つからない場合に自動的に index.html にリダイレクトされるようになります。これにより、React Router などのクライアントサイドルーティングが正しく機能するでしょう。

静的ファイルと動的処理を同居させる

Cloudflare Workers を使うので、サーバーサイドのロジックも実行できます。wrangler.json に以下の設定を追加することで、静的ファイルが見つからない場合に Worker を起動するような構成も可能になります。

{
  "name": "my-spa",
  "compatibility_date": "2025-04-01",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application"
  }
}

ここで追加された binding: "ASSETS" は、Worker コード内で静的アセットにアクセスするための名前を定義しています。これにより、Worker 内で静的ファイルの有無を判断し、柔軟なルーティングや API のハンドリングが可能になります。

この構成を活用することで、例えば /api/* パスへのリクエストを Worker の API ハンドラに転送したり、認証が必要なルートへのアクセス制御を実装したり、エッジでのデータ変換やキャッシュ制御を行ったりといった高度な機能を実装できます。

まとめ

Ionic で React アプリを開発し、Cloudflare Workers にデプロイする方法について解説してきました。 Workers の機能を活用することで静的ファイルのデプロイやSPA ルーティングの問題を解決できます。また、本来の Workers 機能である動的処理部分を同居させることで、1つのリポジトリ・1つのプロジェクトでバックエンドまで用意されたWeb アプリケーションを構築することが可能になります。モノレポ構成でフロントエンドとバックエンドを管理することなども視野に入りそうです。

ぜひこの方法を試して、あなたの Ionic React アプリケーションの開発フローやデプロイ先の幅を広げてみてください。