improve and test vite-plugin-cloudflare .dev.vars files support (#7864)

dario-piotrowicz · jamesopstad · vicb · web-flow · commit de6fa1846ac7 · 2025-01-28T14:52:25.000Z
Co-authored-by: James Opstad &lt;13586373+jamesopstad@users.noreply.github.com&gt;
Co-authored-by: Victor Berchet &lt;victor@suumit.com&gt;
Co-authored-by: Pete Bacon Darwin &lt;pete@bacondarwin.com&gt;
diff --git a/.changeset/orange-camels-hunt_vite-plugin.md b/.changeset/orange-camels-hunt_vite-plugin.md
@@ -0,0 +1,10 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+Add full support for `.dev.vars` files.
+
+This change makes sure that `.dev.vars` files work when the environment is specified. It also
+copies the target `.dev.vars` file (which might be environment specific, e.g. `.dev.vars.prod`)
+to the worker's dist directory so that `vite preview` can pick it up.
+The copied file will always be named `.dev.vars`.
diff --git a/.changeset/orange-camels-hunt_wrangler.md b/.changeset/orange-camels-hunt_wrangler.md
@@ -0,0 +1,9 @@
+---
+"wrangler": minor
+---
+
+Update the `unstable_getMiniflareWorkerOptions` types to always include an `env` parameter.
+
+The `unstable_getMiniflareWorkerOptions` types, when accepting a config object as the first argument,
+didn't accept a second `env` argument. The changes here make sure they do, since the `env` is still
+relevant for picking up variables from `.dev.vars` files.
diff --git a/packages/vite-plugin-cloudflare/README.md b/packages/vite-plugin-cloudflare/README.md
@@ -466,6 +466,13 @@ The value of `MY_VAR` will therefore be `'Production var'`.
 If you run `vite build --mode staging` then the 'staging' Vite mode will be used and the 'staging' Cloudflare environment will be selected.
 The value of `MY_VAR` will therefore be `'Staging var'`.
 
+## Secrets
+
+Secrets can be provided to your Worker in local development using a [`.dev.vars`](https://developers.cloudflare.com/workers/configuration/secrets/#local-development-with-secrets) file. If you are using [Cloudflare Environments](#cloudflare-environments) then the relevant `.dev.vars` file will be selected. For example, `CLOUDFLARE_ENV=staging vite dev` will load `.dev.vars.staging` if it exists and fall back to `.dev.vars`.
+
+> [!NOTE]
+> The `vite build` command copies the relevant `.dev.vars[.env-name]` file to the output directory. This is only used when running `vite preview` and is not deployed with your Worker.
+
 ## Migrating from `wrangler dev`
 
 Migrating from `wrangler dev` is a simple process and you can follow the instructions in the [Quick start](#quick-start) to get started.
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/.dev.vars b/packages/vite-plugin-cloudflare/playground/dev-vars/.dev.vars
@@ -0,0 +1,4 @@
+ENV_NAME = ""
+MY_DEV_VAR_A = "my .dev.vars variable A"
+MY_DEV_VAR_B = "my .dev.vars variable B"
+MY_DEV_VAR_C = "my .dev.vars variable C"
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/.dev.vars.staging b/packages/vite-plugin-cloudflare/playground/dev-vars/.dev.vars.staging
@@ -0,0 +1,3 @@
+ENV_NAME = "staging"
+MY_DEV_VAR_A = "my .dev.vars staging variable A"
+MY_DEV_VAR_B = "my .dev.vars staging variable B"
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/.env.with-specified-env b/packages/vite-plugin-cloudflare/playground/dev-vars/.env.with-specified-env
@@ -0,0 +1 @@
+CLOUDFLARE_ENV=staging
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/.gitignore b/packages/vite-plugin-cloudflare/playground/dev-vars/.gitignore
@@ -0,0 +1 @@
+!.dev.vars*
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/__tests__/dev-vars-loading.spec.ts b/packages/vite-plugin-cloudflare/playground/dev-vars/__tests__/dev-vars-loading.spec.ts
@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import { describe, expect, test } from "vitest";
+import { getJsonResponse, isBuild, testDir } from "../../__test-utils__";
+
+test("reading variables from a standard .dev.vars file", async () => {
+	expect(await getJsonResponse()).toEqual({
+		"variables present in .dev.vars": {
+			MY_DEV_VAR_A: "my .dev.vars variable A",
+			MY_DEV_VAR_B: "my .dev.vars variable B",
+			MY_DEV_VAR_C: "my .dev.vars variable C",
+		},
+	});
+});
+
+describe.runIf(isBuild)("build output files", () => {
+	test("the .dev.vars file has been copied over", async () => {
+		const srcDevVarsPath = `${testDir}/.dev.vars`;
+		const distDevVarsPath = `${testDir}/dist/worker/.dev.vars`;
+
+		const distDevVarsExists = fs.existsSync(distDevVarsPath);
+		expect(distDevVarsExists).toBe(true);
+
+		const srcDevVarsContent = fs.readFileSync(srcDevVarsPath, "utf-8");
+		const distDevVarsContent = fs.readFileSync(distDevVarsPath, "utf-8");
+		expect(distDevVarsContent).toEqual(srcDevVarsContent);
+	});
+
+	test("secrets from .dev.vars haven't been inlined in the js output file", async () => {
+		const distIndexPath = `${testDir}/dist/worker/index.js`;
+
+		const distIndexContent = fs.readFileSync(distIndexPath, "utf-8");
+		expect(distIndexContent).not.toContain("my .dev.vars variable");
+	});
+});
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/__tests__/with-specified-env/dev-vars-loading.spec.ts b/packages/vite-plugin-cloudflare/playground/dev-vars/__tests__/with-specified-env/dev-vars-loading.spec.ts
@@ -0,0 +1,33 @@
+import fs from "node:fs";
+import { describe, expect, test } from "vitest";
+import { getJsonResponse, isBuild, testDir } from "../../../__test-utils__";
+
+test("reading variables from a staging .dev.vars file", async () => {
+	expect(await getJsonResponse()).toEqual({
+		"variables present in .dev.vars.staging": {
+			MY_DEV_VAR_A: "my .dev.vars staging variable A",
+			MY_DEV_VAR_B: "my .dev.vars staging variable B",
+		},
+	});
+});
+
+describe.runIf(isBuild)("build output files", () => {
+	test("the .dev.vars.staging file has been copied over as .dev.vars", async () => {
+		const srcDevVarsStagingPath = `${testDir}/.dev.vars.staging`;
+		const distDevVarsPath = `${testDir}/dist/worker/.dev.vars`;
+		const distDevVarsStagingPath = `${distDevVarsPath}.staging`;
+
+		const distDevVarsExists = fs.existsSync(distDevVarsPath);
+		expect(distDevVarsExists).toBe(true);
+
+		const srcDevVarsStagingContent = fs.readFileSync(
+			srcDevVarsStagingPath,
+			"utf-8"
+		);
+		const distDevVarsContent = fs.readFileSync(distDevVarsPath, "utf-8");
+		expect(distDevVarsContent).toEqual(srcDevVarsStagingContent);
+
+		const distDevVarsStagingExists = fs.existsSync(distDevVarsStagingPath);
+		expect(distDevVarsStagingExists).toBe(false);
+	});
+});
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/package.json b/packages/vite-plugin-cloudflare/playground/dev-vars/package.json
@@ -0,0 +1,19 @@
+{
+	"name": "@playground/dev-vars",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build --app",
+		"check:types": "tsc --build",
+		"dev": "vite dev",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "workspace:*",
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "^4.20241230.0",
+		"typescript": "catalog:vite-plugin",
+		"vite": "catalog:vite-plugin",
+		"wrangler": "catalog:vite-plugin"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/src/index.ts b/packages/vite-plugin-cloudflare/playground/dev-vars/src/index.ts
@@ -0,0 +1,9 @@
+export default {
+	async fetch(_req, env) {
+		const { ENV_NAME, ...dotDevDotVarsVariables } = env;
+		const extension = ENV_NAME ? `.${ENV_NAME}` : "";
+		return Response.json({
+			[`variables present in .dev.vars${extension}`]: dotDevDotVarsVariables,
+		});
+	},
+} satisfies ExportedHandler<Env>;
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/tsconfig.json b/packages/vite-plugin-cloudflare/playground/dev-vars/tsconfig.json
@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.worker.json" }
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/tsconfig.node.json b/packages/vite-plugin-cloudflare/playground/dev-vars/tsconfig.node.json
@@ -0,0 +1,8 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/base.json"],
+	"include": [
+		"vite.config.ts",
+		"vite.config.with-specified-env.ts",
+		"__tests__"
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/tsconfig.worker.json b/packages/vite-plugin-cloudflare/playground/dev-vars/tsconfig.worker.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/worker.json"],
+	"include": ["src", "worker-configuration.d.ts"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/turbo.json b/packages/vite-plugin-cloudflare/playground/dev-vars/turbo.json
@@ -0,0 +1,9 @@
+{
+	"$schema": "http://turbo.build/schema.json",
+	"extends": ["//"],
+	"tasks": {
+		"build": {
+			"outputs": ["dist/**"]
+		}
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/vite.config.ts b/packages/vite-plugin-cloudflare/playground/dev-vars/vite.config.ts
@@ -0,0 +1,6 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [cloudflare({ persistState: false })],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/vite.config.with-specified-env.ts b/packages/vite-plugin-cloudflare/playground/dev-vars/vite.config.with-specified-env.ts
@@ -0,0 +1,7 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	mode: "with-specified-env",
+	plugins: [cloudflare({ persistState: false })],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/worker-configuration.d.ts b/packages/vite-plugin-cloudflare/playground/dev-vars/worker-configuration.d.ts
@@ -0,0 +1,8 @@
+// Generated by Wrangler by running `wrangler types`
+
+interface Env {
+	ENV_NAME: string;
+	MY_DEV_VAR_A: string;
+	MY_DEV_VAR_B: string;
+	MY_DEV_VAR_C: string;
+}
diff --git a/packages/vite-plugin-cloudflare/playground/dev-vars/wrangler.toml b/packages/vite-plugin-cloudflare/playground/dev-vars/wrangler.toml
@@ -0,0 +1,5 @@
+name = "worker"
+main = "./src/index.ts"
+compatibility_date = "2024-12-30"
+
+[env.staging]
diff --git a/packages/vite-plugin-cloudflare/src/index.ts b/packages/vite-plugin-cloudflare/src/index.ts
@@ -198,15 +198,33 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin {
 				}
 
 				config = workerConfig;
+
+				if (workerConfig.configPath) {
+					const dotDevDotVarsContent = getDotDevDotVarsContent(
+						workerConfig.configPath,
+						resolvedPluginConfig.cloudflareEnv
+					);
+					// Save a .dev.vars file to the worker's build output directory
+					// when it exists so that it will be then detected by `vite preview`
+					if (dotDevDotVarsContent) {
+						this.emitFile({
+							type: "asset",
+							fileName: ".dev.vars",
+							source: dotDevDotVarsContent,
+						});
+					}
+				}
 			} else if (this.environment.name === "client") {
 				const assetsOnlyConfig = resolvedPluginConfig.config;
 
 				assetsOnlyConfig.assets.directory = ".";
 
+				const filesToAssetsIgnore = ["wrangler.json", ".dev.vars"];
+
 				this.emitFile({
 					type: "asset",
 					fileName: ".assetsignore",
-					source: "wrangler.json",
+					source: `${filesToAssetsIgnore.join("\n")}\n`,
 				});
 
 				config = assetsOnlyConfig;
@@ -299,3 +317,36 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin {
 		},
 	};
 }
+
+/**
+ * Gets the content of a the potential `.dev.vars` target file
+ *
+ * Note: This resolves the .dev.vars file path following the same logic
+ *       as `loadDotEnv` in `/packages/wrangler/src/config/index.ts`
+ *       the two need to be kept in sync
+ *
+ * @param configPath the path to the worker's wrangler config file
+ * @param cloudflareEnv the target cloudflare environment
+ */
+function getDotDevDotVarsContent(
+	configPath: string,
+	cloudflareEnv: string | undefined
+) {
+	const configDir = path.dirname(configPath);
+
+	const defaultDotDevDotVarsPath = `${configDir}/.dev.vars`;
+	const inputDotDevDotVarsPath = `${defaultDotDevDotVarsPath}${cloudflareEnv ? `.${cloudflareEnv}` : ""}`;
+
+	const targetPath = fs.existsSync(inputDotDevDotVarsPath)
+		? inputDotDevDotVarsPath
+		: fs.existsSync(defaultDotDevDotVarsPath)
+			? defaultDotDevDotVarsPath
+			: null;
+
+	if (targetPath) {
+		const dotDevDotVarsContent = fs.readFileSync(targetPath);
+		return dotDevDotVarsContent;
+	}
+
+	return null;
+}
diff --git a/packages/vite-plugin-cloudflare/src/miniflare-options.ts b/packages/vite-plugin-cloudflare/src/miniflare-options.ts
@@ -280,10 +280,13 @@ export function getDevMiniflareOptions(
 		resolvedPluginConfig.type === "workers"
 			? Object.entries(resolvedPluginConfig.workers).map(
 					([environmentName, workerConfig]) => {
-						const miniflareWorkerOptions = unstable_getMiniflareWorkerOptions({
-							...workerConfig,
-							assets: undefined,
-						});
+						const miniflareWorkerOptions = unstable_getMiniflareWorkerOptions(
+							{
+								...workerConfig,
+								assets: undefined,
+							},
+							resolvedPluginConfig.cloudflareEnv
+						);
 
 						const { ratelimits, ...workerOptions } =
 							miniflareWorkerOptions.workerOptions;
diff --git a/packages/vite-plugin-cloudflare/src/plugin-config.ts b/packages/vite-plugin-cloudflare/src/plugin-config.ts
@@ -47,6 +47,7 @@ export interface WorkerConfig extends BaseConfig {
 interface BasePluginConfig {
 	configPaths: Set<string>;
 	persistState: PersistState;
+	cloudflareEnv: string | undefined;
 }
 
 interface AssetsOnlyPluginConfig extends BasePluginConfig {
@@ -82,7 +83,11 @@ export function resolvePluginConfig(
 	const configPaths = new Set<string>();
 	const persistState = pluginConfig.persistState ?? true;
 	const root = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
-	const { CLOUDFLARE_ENV } = vite.loadEnv(viteEnv.mode, root, "");
+	const { CLOUDFLARE_ENV: cloudflareEnv } = vite.loadEnv(
+		viteEnv.mode,
+		root,
+		/* prefixes */ ""
+	);
 
 	const configPath = pluginConfig.configPath
 		? path.resolve(root, pluginConfig.configPath)
@@ -93,14 +98,10 @@ export function resolvePluginConfig(
 		`Config not found. Have you created a wrangler.json(c) or wrangler.toml file?`
 	);
 
-	const entryWorkerResolvedConfig = getWorkerConfig(
-		configPath,
-		CLOUDFLARE_ENV,
-		{
-			visitedConfigPaths: configPaths,
-			isEntryWorker: true,
-		}
-	);
+	const entryWorkerResolvedConfig = getWorkerConfig(configPath, cloudflareEnv, {
+		visitedConfigPaths: configPaths,
+		isEntryWorker: true,
+	});
 
 	if (entryWorkerResolvedConfig.type === "assets-only") {
 		return {
@@ -111,6 +112,7 @@ export function resolvePluginConfig(
 			rawConfigs: {
 				entryWorker: entryWorkerResolvedConfig,
 			},
+			cloudflareEnv,
 		};
 	}
 
@@ -129,7 +131,7 @@ export function resolvePluginConfig(
 	for (const auxiliaryWorker of pluginConfig.auxiliaryWorkers ?? []) {
 		const workerResolvedConfig = getWorkerConfig(
 			path.resolve(root, auxiliaryWorker.configPath),
-			CLOUDFLARE_ENV,
+			cloudflareEnv,
 			{
 				visitedConfigPaths: configPaths,
 			}
@@ -167,5 +169,6 @@ export function resolvePluginConfig(
 			entryWorker: entryWorkerResolvedConfig,
 			auxiliaryWorkers: auxiliaryWorkersResolvedConfigs,
 		},
+		cloudflareEnv,
 	};
 }
diff --git a/packages/wrangler/src/api/integrations/platform/index.ts b/packages/wrangler/src/api/integrations/platform/index.ts
@@ -249,7 +249,8 @@ export function unstable_getMiniflareWorkerOptions(
 	env?: string
 ): Unstable_MiniflareWorkerOptions;
 export function unstable_getMiniflareWorkerOptions(
-	config: Config
+	config: Config,
+	env?: string
 ): Unstable_MiniflareWorkerOptions;
 export function unstable_getMiniflareWorkerOptions(
 	configOrConfigPath: string | Config,
diff --git a/packages/wrangler/src/config/index.ts b/packages/wrangler/src/config/index.ts
@@ -222,6 +222,10 @@ function tryLoadDotEnv(basePath: string): DotEnv | undefined {
 /**
  * Loads a dotenv file from `envPath`, preferring to read `${envPath}.${env}` if
  * `env` is defined and that file exists.
+ *
+ * Note: The `getDotDevDotVarsContent` function in the `packages/vite-plugin-cloudflare/src/index.ts` file
+ *       follows the same logic implemented here, the two need to be kept in sync, so if you modify some logic
+ *       here make sure that, if applicable, the same change is reflected there
  */
 export function loadDotEnv(envPath: string, env?: string): DotEnv | undefined {
 	if (env === undefined) {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+ENV_NAME = "staging"`
	`2`	`+MY_DEV_VAR_A = "my .dev.vars staging variable A"`
	`3`	`+MY_DEV_VAR_B = "my .dev.vars staging variable B"`