Vite 環境

Vite 6 で公開された Vite Environment API ↗ は、Cloudflare Vite プラグインが Vite を Workers ランタイムと直接つなぐための中核機能です。 エンドユーザーとして Environment API の細部まで理解する必要はありませんが、概要を把握しておくと便利です。

Vite は既定で client と ssr の 2 つの環境を作ります。 フロントエンドだけのアプリケーションは client 環境を使います。フレームワークで作ったフルスタックアプリケーションは、通常、フロントエンドコードに client 環境、サーバーサイドレンダリングに ssr 環境を使います。

Cloudflare Vite プラグインで Worker を追加すると、既定でもう 1 つ環境が作られます。 名前は Worker 名から派生し、ハイフンはアンダースコアに置き換わります。 この名前を Vite 設定で参照し、環境ごとの設定を適用できます。

次の例では、my-worker という Worker が my_worker という Vite 環境に対応しています。 この環境向けのグローバル定数の置き換えを、Vite 設定で指定します。

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

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./src/index.ts"

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

export default defineConfig({
	environments: {
		my_worker: {
			define: {
				__APP_VERSION__: JSON.stringify("v1.0.0"),
			},
		},
	},
	plugins: [cloudflare()],
});

Vite の設定オプションについて詳しくは、Configuring Vite ↗ を参照してください。

スタンドアロンの Worker（フロントエンドアプリケーションからアクセスする API や、サービスバインディング経由でアクセスする auxiliary Worker）では、Worker 名を環境名にする既定の動作が適しています。

Cloudflare Vite プラグインを TanStack Start ↗ または React Router v8 ↗ と使う場合、Worker はサーバーサイドレンダリングに使われ、フレームワークと密に統合されます。 これを支えるため、プラグイン設定の viteEnvironment.name で ssr 環境に割り当ててください。

import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";
import { reactRouter } from "@react-router/dev/vite";

export default defineConfig({
	plugins: [cloudflare({ viteEnvironment: { name: "ssr" } }), reactRouter()],
});

これにより、Worker の環境設定がフレームワークの SSR 設定とマージされ、Worker がフレームワークのビルド出力に含まれます。