Support CLOUDFLARE_ENV environment variable for selecting the active environment (#11228)

* Make BundleController tests able to run on non-unix OSs

* ignore generated files from eslint

* fix home directory mocking

* Improve isolation of containers push tests

* use logger.loggerLevel rather than recomputing it in Wrangler

The startup-profiling test was leaking the logger level between tests,
so that got fixed in here too.

* move environment variable handling from `wrangler` to `@cloudflare/workers-utils`

* Support `CLOUDFLARE_ENV` environment variable for selecting the active environment

This change enables users to select the environment for commands such as `CLOUDFLARE_ENV=prod wrangler versions upload`.
The `--env` command line argument takes precedence.

The `CLOUDFLARE_ENV` enviroment variable is mostly used with the `@cloudflare/vite-plugin` to select the environment for building
the Worker to be deployed. This build also generates a "redirected deploy config" that is flattened to only contain the active environment.
To avoid accidentally deploying a version that is built for one environment to a different environment, there is an additional
check to ensure that if the user specifies an environment in Wrangler it matches the original selected environment from the build.

* fix error message when both CLOUDFLARE_ENV and --env are provided

* fix "via" part of the validation error

* fixups after James' review

* send the errors to Sentry so we can ascertain how often this occurs

* fixups from Dario

Author: petebacondarwin

.changeset/soft-rockets-draw.md

@@ -0,0 +1,11 @@
+---
+"@cloudflare/workers-utils": minor
+"wrangler": minor
+---
+
+Support `CLOUDFLARE_ENV` environment variable for selecting the active environment
+
+This change enables users to select the environment for commands such as `CLOUDFLARE_ENV=prod wrangler versions upload`. The `--env` command line argument takes precedence.
+
+The `CLOUDFLARE_ENV` environment variable is mostly used with the `@cloudflare/vite-plugin` to select the environment for building the Worker to be deployed. This build also generates a "redirected deploy config" that is flattened to only contain the active environment.
+To avoid accidentally deploying a version that is built for one environment to a different environment, there is an additional check to ensure that if the user specifies an environment in Wrangler it matches the original selected environment from the build.

fixtures/redirected-config-worker/package.json

@@ -9,7 +9,7 @@
 		"build": "node -r esbuild-register tools/build.ts",
 		"check:type": "tsc",
 		"dev": "pnpm run build && wrangler dev",
-		"test:ci": "pnpm run build && vitest run"
+		"test:ci": "vitest run"
 	},
 	"devDependencies": {
 		"@cloudflare/workers-tsconfig": "workspace:^",

fixtures/redirected-config-worker/tests/index.test.ts

@@ -1,12 +1,14 @@
+import { execSync } from "child_process";
 import { resolve } from "path";
 import { fetch } from "undici";
 import { describe, it } from "vitest";
 import { runWranglerDev } from "../../shared/src/run-wrangler-long-lived";
 
 const basePath = resolve(__dirname, "..");
 
-describe("'wrangler dev' correctly renders pages", () => {
+describe("'wrangler dev', when reading redirected config,", () => {
 	it("uses the generated config", async ({ expect, onTestFinished }) => {
+		build("prod");
 		const { ip, port, stop } = await runWranglerDev(basePath, [
 			"--port=0",
 			"--inspector-port=0",
@@ -17,20 +19,76 @@ describe("'wrangler dev' correctly renders pages", () => {
 		const response = await fetch(`http://${ip}:${port}/`);
 		const text = await response.text();
 		expect(response.status).toBe(200);
-		expect(text).toMatchInlineSnapshot(`"Generated: true"`);
+		expect(text).toMatchInlineSnapshot(`"Generated: prod"`);
 	});
 
-	it("specifying an environment causes an error since they are not supported in redirected configs", async ({
+	it("works when specifying the same environment via CLI arg to the one used in build", async ({
 		expect,
+		onTestFinished,
 	}) => {
-		await expect(
-			runWranglerDev(basePath, [
-				"--port=0",
-				"--inspector-port=0",
-				"--env=staging",
-			])
-		).rejects.toThrowError(
-			/You have specified the environment ".*?", but are using a redirected configuration/
+		build("production");
+
+		const { ip, port, stop } = await runWranglerDev(basePath, [
+			"--port=0",
+			"--inspector-port=0",
+			"--env=production",
+		]);
+		onTestFinished(async () => await stop?.());
+
+		const response = await fetch(`http://${ip}:${port}/`);
+		const text = await response.text();
+		expect(response.status).toBe(200);
+		expect(text).toMatchInlineSnapshot(`"Generated: production"`);
+	});
+
+	it("errors when specifying a different environment via CLI arg to the one used in build", async ({
+		expect,
+	}) => {
+		build("production");
+
+		const error = await runWranglerDev(basePath, [
+			"--port=0",
+			"--inspector-port=0",
+			"--env=staging",
+		]).then(
+			// it is doesn't error then stop the process
+			({ stop }) => stop(),
+			(e) => e
+		);
+
+		expect(error).toMatch(
+			'You have specified the environment "staging" via the `--env/-e` CLI argument.'
+		);
+		expect(error).toMatch(
+			'This does not match the target environment "production" that was used when building the application.'
+		);
+		expect(error).toMatch(
+			'Perhaps you need to re-run the custom build of the project with "staging" as the selected environment?'
+		);
+	});
+
+	it("errors when specifying a different environment via CLOUDFLARE_ENV to the one used in build", async ({
+		expect,
+	}) => {
+		build("production");
+
+		let error = "";
+		try {
+			await runWranglerDev(basePath, ["--port=0", "--inspector-port=0"], {
+				CLOUDFLARE_ENV: "staging",
+			});
+		} catch (e) {
+			error = e as string;
+		}
+
+		expect(error).toMatch(
+			'You have specified the environment "staging" via the CLOUDFLARE_ENV environment variable.'
+		);
+		expect(error).toMatch(
+			'This does not match the target environment "production" that was used when building the application.'
+		);
+		expect(error).toMatch(
+			'Perhaps you need to re-run the custom build of the project with "staging" as the selected environment?'
 		);
 	});
 
@@ -52,3 +110,10 @@ describe("'wrangler dev' correctly renders pages", () => {
 		expect(text).toMatchInlineSnapshot(`"Generated: undefined"`);
 	});
 });
+
+function build(env: string) {
+	execSync("node -r esbuild-register tools/build.ts", {
+		cwd: basePath,
+		env: { ...process.env, CLOUDFLARE_ENV: env },
+	});
+}

fixtures/redirected-config-worker/tools/build.ts

@@ -7,7 +7,8 @@ const config = {
 	name: "redirected-config-worker",
 	compatibility_date: "2024-12-01",
 	main: "index.js",
-	vars: { generated: true },
+	targetEnvironment: process.env.CLOUDFLARE_ENV,
+	vars: { generated: process.env.CLOUDFLARE_ENV ?? "none" },
 };
 writeFileSync("build/wrangler.json", JSON.stringify(config, undefined, 2));
 copyFileSync("src/index.js", "build/index.js");

fixtures/redirected-config-worker/wrangler.jsonc

@@ -2,4 +2,16 @@
 	"name": "redirected-config-worker",
 	"compatibility_date": "2024-12-01",
 	"main": "src/index.js",
+	"env": {
+		"staging": {
+			"vars": {
+				"generated": "none",
+			},
+		},
+		"prod": {
+			"vars": {
+				"generated": "none",
+			},
+		},
+	},
 }

packages/containers-shared/tests/helpers/run-in-tmp-dir.ts

@@ -24,29 +24,20 @@ export function runInTempDir({ homedir } = { homedir: "./home" }) {
 		);
 
 		process.chdir(tmpDir);
-		// eslint-disable-next-line turbo/no-undeclared-env-vars
-		process.env.PWD = tmpDir;
-
-		// The path that is returned from `homedir()` should be absolute.
-		const absHomedir = path.resolve(tmpDir, homedir);
+		vi.stubEnv("PWD", tmpDir);
 
 		// Override where the home directory is so that we can write our own user config,
 		// without destroying the real thing.
+		// The path that is returned from `homedir()` should be absolute.
+		const absHomedir = path.resolve(tmpDir, homedir);
 		fs.mkdirSync(absHomedir, { recursive: true });
-
-		// Note it is very important that we use the "default" value from "node:os" (e.g. `import os from "node:os";`)
-		// rather than an alias to the module (e.g. `import * as os from "node:os";`).
-		// This is because the module gets transpiled so that the "method" `homedir()` gets converted to a
-		// getter that is not configurable (and so cannot be spied upon).
-		vi.spyOn(os, "homedir")?.mockReturnValue(absHomedir);
+		vi.stubEnv("HOME", absHomedir);
+		vi.stubEnv("XDG_CONFIG_HOME", path.resolve(absHomedir, ".config"));
 	});
 
 	afterEach(() => {
+		process.chdir(originalCwd);
 		if (fs.existsSync(tmpDir)) {
-			process.chdir(originalCwd);
-			// eslint-disable-next-line turbo/no-undeclared-env-vars
-			process.env.PWD = originalCwd;
-
 			// Don't block on deleting the tmp dir
 			void rm(tmpDir).catch(() => {
 				// Best effort - try once then just move on - they are only temp files after all.

packages/workers-utils/package.json

@@ -52,7 +52,8 @@
 		"tsdown": "^0.15.9",
 		"tsup": "8.3.0",
 		"typescript": "catalog:default",
-		"vitest": "catalog:default"
+		"vitest": "catalog:default",
+		"xdg-app-paths": "^8.3.0"
 	},
 	"volta": {
 		"extends": "../../package.json"

packages/workers-utils/src/config/validation.ts

@@ -3,6 +3,7 @@ import path from "node:path";
 import { isDockerfile } from "@cloudflare/containers-shared";
 import { isValidWorkflowName } from "@cloudflare/workflows-shared/src/lib/validators";
 import { dedent } from "ts-dedent";
+import { getCloudflareEnv } from "../environment-variables/misc-variables";
 import { UserError } from "../errors";
 import { isRedirectedRawConfig } from "./config-helpers";
 import { Diagnostics } from "./diagnostics";
@@ -257,21 +258,32 @@ export function normalizeAndValidateConfig(
 		);
 	}
 
-	//TODO: find a better way to define the type of Args that can be passed to the normalizeAndValidateConfig()
-	const envName = args.env;
+	// The environment can come from the CLI args (i.e. `--env`) or from the `CLOUDFLARE_ENV` environment variable.
+	const envName = args.env ?? getCloudflareEnv();
 	assert(envName === undefined || typeof envName === "string");
 
 	let activeEnv = topLevelEnv;
 
 	if (envName) {
 		if (isRedirectedConfig) {
-			// Note: we error if the user is specifying an environment, but not for pages
-			//       commands where the environment is always set (to either "preview" or "production")
-			if (!isPagesConfig(rawConfig)) {
-				diagnostics.errors.push(dedent`
-					You have specified the environment "${envName}", but are using a redirected configuration, produced by a build tool such as Vite.
-					You need to set the environment in your build tool, rather than via Wrangler.
-					For example, if you are using Vite, refer to these docs: https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/
+			// Check that if we are loading a redirected config, any specified environment must match the target environment
+			// from the original user config.
+			// Note: we don't error for pages commands where the environment is always set (to either "preview" or "production")
+			if (
+				!isPagesConfig(rawConfig) &&
+				rawConfig.targetEnvironment &&
+				rawConfig.targetEnvironment !== envName
+			) {
+				const via =
+					args.env !== undefined
+						? "via the `--env/-e` CLI argument"
+						: "via the CLOUDFLARE_ENV environment variable";
+				// We are throwing here rather than just adding to the diagnostics because this is a hard error
+				// and we'd like to collect Sentry data on when and how often this is happening.
+				throw new Error(dedent`
+					You have specified the environment "${envName}" ${via}.
+					This does not match the target environment "${rawConfig.targetEnvironment}" that was used when building the application.
+					Perhaps you need to re-run the custom build of the project with "${envName}" as the selected environment?
 				`);
 			}
 		} else {

…ler/src/environment-variables/factory.ts …ils/src/environment-variables/factory.tspackages/wrangler/src/environment-variables/factory.ts renamed to packages/workers-utils/src/environment-variables/factory.ts packages/wrangler/src/environment-variables/factory.ts renamed to packages/workers-utils/src/environment-variables/factory.ts

@@ -1,4 +1,4 @@
-import { UserError } from "@cloudflare/workers-utils";
+import { UserError } from "../errors";
 
 /**
  * Environment variables supported by Wrangler for configuration and authentication.
@@ -66,6 +66,8 @@ type VariableNames =
 	| "WRANGLER_REGISTRY_PATH"
 	/** Additional D1 location choices (internal use). */
 	| "WRANGLER_D1_EXTRA_LOCATION_CHOICES"
+	/** The Workers environment to target (equivalent to the `--env` CLI param) */
+	| "CLOUDFLARE_ENV"
 
 	// ## Advanced Configuration
 

…/environment-variables/misc-variables.ts …/environment-variables/misc-variables.tspackages/wrangler/src/environment-variables/misc-variables.ts renamed to packages/workers-utils/src/environment-variables/misc-variables.ts packages/wrangler/src/environment-variables/misc-variables.ts renamed to packages/workers-utils/src/environment-variables/misc-variables.ts

@@ -1,12 +1,12 @@
 import path from "node:path";
-import { UserError } from "@cloudflare/workers-utils";
 import { dedent } from "ts-dedent";
+import { UserError } from "../errors";
 import { getGlobalWranglerConfigPath } from "../global-wrangler-config-path";
 import {
 	getBooleanEnvironmentVariableFactory,
 	getEnvironmentVariableFactory,
 } from "./factory";
-import type { Config } from "@cloudflare/workers-utils";
+import type { Config } from "../config";
 
 /**
  * `WRANGLER_C3_COMMAND` can override the command used by `wrangler init` when delegating to C3.
@@ -321,3 +321,10 @@ export const getWranglerHideBanner = getBooleanEnvironmentVariableFactory({
 	variableName: "WRANGLER_HIDE_BANNER",
 	defaultValue: false,
 });
+
+/**
+ * `CLOUDFLARE_ENV` specifies the currently selected Wrangler/Cloudflare environment.
+ */
+export const getCloudflareEnv = getEnvironmentVariableFactory({
+	variableName: "CLOUDFLARE_ENV",
+});