React + Vite

create-cloudflare CLI（C3）で新規プロジェクトを作成する

npm create cloudflare@latest -- my-react-app --framework=react

yarn create cloudflare my-react-app --framework=react

pnpm create cloudflare@latest my-react-app --framework=react

Cloudflare Vite プラグイン でローカル開発する

プロジェクトを作成したあと、プロジェクトディレクトリで次のコマンドを実行し、ローカル開発サーバーを起動します。

npm run dev

yarn run dev

pnpm run dev

プロジェクトをデプロイする

プロジェクトは、自分のマシンまたは任意の CI/CD（Cloudflare の Workers Builds を含む）から、*.workers.dev サブドメインまたは Custom Domain にデプロイできます。

次のコマンドでビルドとデプロイを行います。CI を使う場合は、"デプロイコマンド" の設定を適切に更新してください。

npm run deploy

yarn run deploy

pnpm run deploy

プロジェクトディレクトリを開く

既存の React + Vite プロジェクトを、使っているエディターで開きます。まだない場合は、先に Vite で新規プロジェクトを足場にします。

npm create vite@latest -- my-react-app --template react-ts

yarn create vite my-react-app --template react-ts

pnpm create vite@latest my-react-app --template react-ts

次に、my-react-app ディレクトリをエディターで開きます。

Cloudflare Vite プラグインを追加する

npm i -D @cloudflare/vite-plugin wrangler

yarn add -D @cloudflare/vite-plugin wrangler

pnpm add -D @cloudflare/vite-plugin wrangler

bun add -d @cloudflare/vite-plugin wrangler

vite.config.ts で、フレームワークのプラグインのあとに Cloudflare Vite プラグインを追加します。

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
	plugins: [react(), cloudflare()],
});

Cloudflare Vite プラグインは、既定では設定不要です。アプリケーションのルートにある wrangler.jsonc、wrangler.json、または wrangler.toml を探します。

設定オプションは API リファレンス を参照してください。

Wrangler 設定ファイルを追加する

プロジェクトのルートに wrangler.jsonc ファイルを作成します。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Set this to today's date
  "compatibility_date": "2026-09-20",
  "assets": {
    "not_found_handling": "single-page-application"
  }
}

name = "my-app"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
not_found_handling = "single-page-application"

not_found_handling の値は single-page-application に設定しています。 存在しないパスへのリクエストはすべて index.html を返します。React Router など、クライアントサイドルーティングのソリューションではこの設定が必要です。

Cloudflare プラグインでは、Vite のデフォルト動作の代わりに assets のルーティング設定を使います。 これにより、開発中も本番へデプロイしたときも、アプリケーションの ルーティング設定 は同じように動きます。

Vite でアセットを設定する場合、directory フィールドは使いません。 出力設定の directory は、クライアントのビルド出力を自動的に指します。 詳しくは 静的アセット を参照してください。

.gitignore ファイルを更新する

Workers を開発する際、Git に保存すべきでない追加ファイルが使われたり生成されたりします。 次の行を .gitignore ファイルに追加します。

.wrangler
.dev.vars*

ローカルで開発する

フレームワークの開発コマンドを実行し、Vite の開発サーバーを起動して、アプリケーションが想定どおりに動くことを確認します。

npm run dev

yarn run dev

pnpm run dev

フロントエンドのみのアプリケーションであれば、このあとビルド、プレビュー、デプロイできます。 以降のセクションでは、さらに進めて API Worker を追加する方法を説明します。

プロジェクトをビルドしてデプロイする

ビルドコマンドを実行して、アプリケーションをビルドします。

npm run build

yarn run build

pnpm run build

dist ディレクトリには、クライアントのビルド出力が client サブディレクトリに入り、Worker のコードと出力された wrangler.json 設定ファイルが同じ場所に置かれます。

preview コマンドを実行して、アプリケーションが想定どおりに動作することを確認します。

npm run preview

yarn run preview

pnpm run preview

このコマンドは、ビルド出力をローカルの Workers ランタイムで実行します。本番環境での動作に近い形で確認できます。

デプロイコマンドを実行して、アプリケーションを Cloudflare へデプロイします。

npx wrangler deploy

yarn wrangler deploy

pnpm wrangler deploy

このコマンドは、ビルド出力に含まれる wrangler.json を自動的に使います。

Worker コード用に TypeScript を設定する

npm i -D @cloudflare/workers-types

yarn add -D @cloudflare/workers-types

pnpm add -D @cloudflare/workers-types

bun add -d @cloudflare/workers-types

Node の TypeScript 設定を継承し、Workers の型を追加する tsconfig.worker.json を作成します。

{
	"extends": "./tsconfig.node.json",
	"compilerOptions": {
		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.worker.tsbuildinfo",
		"types": ["@cloudflare/workers-types/2023-07-01", "vite/client"],
	},
	"include": ["worker"],
}

次に、ルートの tsconfig.json から、この新しい設定を参照します。

{
	"files": [],
	"references": [
		{ "path": "./tsconfig.app.json" },
		{ "path": "./tsconfig.node.json" },
		{ "path": "./tsconfig.worker.json" },
	],
}

設定に Worker のエントリポイントを追加する

Wrangler 設定ファイルを更新し、Worker のエントリポイントを指す main フィールドを追加します。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-app",
  // Set this to today's date
  "compatibility_date": "2026-09-20",
  "main": "./worker/index.ts",
  "assets": {
    "not_found_handling": "single-page-application"
  }
}

name = "my-app"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./worker/index.ts"

[assets]
not_found_handling = "single-page-application"

main フィールドは、Worker コードのエントリファイルを指定します。

API Worker を追加する

次の内容で worker/index.ts ファイルを作成します。

export default {
	fetch(request) {
		const url = new URL(request.url);

		if (url.pathname.startsWith("/api/")) {
			return Response.json({
				name: "Cloudflare",
			});
		}

		return new Response(null, { status: 404 });
	},
} satisfies ExportedHandler;

前のコードブロックで定義した Worker は、静的アセットに一致しないナビゲーション以外のリクエストで呼び出されます。 pathname が /api/ で始まる場合は JSON レスポンスを返し、それ以外は 404 レスポンスを返します。

クライアントから API を呼び出す

React コンポーネントから API を呼べます。たとえば src/App.tsx では:

import { useState } from "react";

function App() {
	const [name, setName] = useState("unknown");

	return (
		<div className="card">
			<button
				onClick={() => {
					fetch("/api/")
						.then((res) => res.json() as Promise<{ name: string }>)
						.then((data) => setName(data.name));
				}}
			>
				Name from API is: {name}
			</button>
		</div>
	);
}

export default App;