Support `CLOUDFLARE_ENV` environment variable for selecting the active environment by petebacondarwin · Pull Request #11228 · cloudflare/workers-sdk

petebacondarwin · 2025-11-09T15:21:16Z

Fixes #10928
Replaces #10940 (thanks @eduardo-vargas).

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.

Reviewer Notes

The first 5 commits are tidy ups from me trying to get this PR to be green. If necessary I can pull them out in a separate PR that gets landed first.
The 6th commit is a big one but it is mostly just moving the environment variables handling over to workers-utils and updating all the imports
The 7th (and last commit barring any fixups) is the one that actually adds support and appropriate warnings to Wrangler for the CLOUDFLARE_ENV variable

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s): Document CLOUDFLARE_ENV environment variable for Wrangler cloudflare-docs#26400
- Documentation not necessary because:
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: features are not backported.

changeset-bot · 2025-11-09T15:21:20Z

🦋 Changeset detected

Latest commit: f482fc4

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-11-09T15:24:28Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@11228

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@11228

miniflare

npm i https://pkg.pr.new/miniflare@11228

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@11228

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@11228

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@11228

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@11228

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@11228

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@11228

wrangler

npm i https://pkg.pr.new/wrangler@11228

commit: f482fc4

- Add CLOUDFLARE_ENV to system environment variables documentation - Update environments documentation to mention CLOUDFLARE_ENV usage - Add changelog entry for the new feature Related to cloudflare/workers-sdk#11228 Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

ascorbic · 2025-11-10T11:41:11Z

I think these test failures are legit, as they are related to enviornments

petebacondarwin · 2025-11-10T12:41:36Z

Yeah sorry @ascorbic - I am working on it. I meant to set this back to "draft".

petebacondarwin · 2025-11-11T09:26:59Z

packages/wrangler/src/index.ts

-			setLogLevel(envLogLevel as LoggerLevel);
 		}
+		// Also set the CLI package log level to match
+		setLogLevel(logger.loggerLevel);


The loggerLevel property is actually a getter that computes the level taking into account the current ALS.

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

jamesopstad

As discussed in chat, if CLOUDFLARE_ENV is also read via dotenv in Wrangler then I am less convinced this is a good idea. Imagine the following example:

.env

CLOUDFLARE_ENV=development

.env.production

CLOUDFLARE_ENV=production

The build is run using vite build --mode production, which reads .env.production. Running wrangler deploy would then read .env and so the selected CLOUDFLARE_ENV value would not match the build.

packages/wrangler/src/__tests__/containers/push.test.ts

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

packages/workers-utils/src/index.ts

petebacondarwin · 2025-11-11T10:48:26Z

As discussed in chat, if CLOUDFLARE_ENV is also read via dotenv in Wrangler then I am less convinced this is a good idea. Imagine the following example:

.env
CLOUDFLARE_ENV=development
.env.production
CLOUDFLARE_ENV=production
The build is run using vite build --mode production, which reads .env.production. Running wrangler deploy would then read .env and so the selected CLOUDFLARE_ENV value would not match the build.

Dropping our offline conversation in here for transparency...

Looking at our docs, we do not recommend that the user puts CLOUDFLARE_ENV in the .env file.

https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/#combining-cloudflare-environments-and-vite-modes

Instead we only give examples of putting it in .env.production or .env.staging.

If there is not a CLOUDFLARE_ENV in the .env file then everything will work fine, since as far as Wrangler is concerned there is no CLOUDFLARE_ENV var set and so it will just deploy the redirected config as-is.

We could update the docs to explicitly call out not putting CLOUDFLARE_ENV in the .env file.

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

…rkers-utils`

…e 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.

dario-piotrowicz · 2025-11-24T14:54:18Z

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

-			/You have specified the environment ".*?", but are using a redirected configuration/
+			]);
+		} catch (e) {
+			error = e as string;


isn't e already an any?

Suggested change

error = e as string;

error = e;

You're right! For some reason I always assume that the thing being caught is types as unknown, not any.

dario-piotrowicz · 2025-11-24T14:55:28Z

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

+
+		let error = "";
+		try {
+			const { getOutput } = await runWranglerDev(basePath, [


Suggested change

const { getOutput } = await runWranglerDev(basePath, [

await runWranglerDev(basePath, [

getOutput is not being used anywhere, is it?

* Document CLOUDFLARE_ENV environment variable for Wrangler - Add CLOUDFLARE_ENV to system environment variables documentation - Update environments documentation to mention CLOUDFLARE_ENV usage - Add changelog entry for the new feature Related to cloudflare/workers-sdk#11228 Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com> * Update changelog to combine build and deploy commands with & Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com> * Add link to generated wrangler configuration docs in changelog Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

PetarMetodiev · 2025-12-16T10:04:07Z

As discussed in chat, if CLOUDFLARE_ENV is also read via dotenv in Wrangler then I am less convinced this is a good idea. Imagine the following example:
.env
CLOUDFLARE_ENV=development
.env.production
CLOUDFLARE_ENV=production
The build is run using vite build --mode production, which reads .env.production. Running wrangler deploy would then read .env and so the selected CLOUDFLARE_ENV value would not match the build.
Dropping our offline conversation in here for transparency...

Looking at our docs, we do not recommend that the user puts CLOUDFLARE_ENV in the .env file.

https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/#combining-cloudflare-environments-and-vite-modes

Instead we only give examples of putting it in .env.production or .env.staging.

If there is not a CLOUDFLARE_ENV in the .env file then everything will work fine, since as far as Wrangler is concerned there is no CLOUDFLARE_ENV var set and so it will just deploy the redirected config as-is.

We could update the docs to explicitly call out not putting CLOUDFLARE_ENV in the .env file.

Folks, sorry to resurrect a merged PR, but this cost me a couple days of debugging and I think it is worth addressing because it is an easy footgun.

I have a project with multiple dotenv files (.env, .env.production, .env.staging, etc.) and for consistency each one defines CLOUDFLARE_ENV=..., including the default .env (mine has CLOUDFLARE_ENV=dev).

What happens in my setup:

Build: I run vite build --mode production. Vite loads .env.production, so the build is produced with CLOUDFLARE_ENV=production and generates the redirected Wrangler config for that environment.
Deploy: Later I run wrangler deploy (without --env). Wrangler loads .env via dotenv, sees CLOUDFLARE_ENV=dev, and then selects the active environment as dev. This is effectively the same as running wrangler deploy --env dev, even though I did not pass --env.

This results in a confusing warning like:

▲ [WARNING] Processing build/server/wrangler.json configuration:

- No environment found in configuration with name "dev".
  Before using `--env=dev` there should be an equivalent environment section in the configuration.

  Consider adding an environment configuration section to the wrangler.json file:
  [env.dev]That message sent me down the wrong path. My issue was not "I forgot to add `[env.dev]`". My issue was "Wrangler picked up `CLOUDFLARE_ENV=dev` from `.env` via dotenv and treated it as an environment selection, while my build used a different mode and environment".

I see the docs recommend setting CLOUDFLARE_ENV in mode-specific files like .env.production or .env.staging, but they do not explicitly warn against defining it in the default .env, which is a common pattern when people try to keep env files uniform: Combining Cloudflare environments and Vite modes.

Could you please consider one of the following?

Docs: explicitly call out "Do not set CLOUDFLARE_ENV in .env; only set it in .env.<mode> files" (or otherwise clarify that Wrangler reads dotenv and will treat CLOUDFLARE_ENV as environment selection).
Error/warning UX: change the warning to mention CLOUDFLARE_ENV and dotenv explicitly (for example: "CLOUDFLARE_ENV=dev was loaded from .env. This makes Wrangler behave like --env dev. If you built with --mode production, move CLOUDFLARE_ENV to .env.production or unset it for deploy.")
Behavior (if appropriate): reconsider reading CLOUDFLARE_ENV from dotenv by default, or adjust precedence, so wrangler deploy does not unexpectedly behave like --env was passed.

Happy to open a new issue if that is preferred.

Thanks!

petebacondarwin requested review from a team as code owners November 9, 2025 15:21

workers-devprod added this to workers-sdk Nov 9, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Nov 9, 2025

petebacondarwin mentioned this pull request Nov 9, 2025

feat: respect CLOUDFLARE_ENV as a fallback for --env #10940

Closed

6 tasks

petebacondarwin mentioned this pull request Nov 9, 2025

CLOUDFLARE_ENV is not documented as a system environment variables cloudflare/cloudflare-docs#25785

Closed

petebacondarwin mentioned this pull request Nov 9, 2025

Document CLOUDFLARE_ENV environment variable for Wrangler cloudflare/cloudflare-docs#26400

Merged

4 tasks

petebacondarwin force-pushed the pbd/support-CLOUDFLARE_ENV-in-wrangler branch 3 times, most recently from 04c0b77 to b7c64fc Compare November 10, 2025 09:31

petebacondarwin marked this pull request as draft November 10, 2025 12:41

petebacondarwin force-pushed the pbd/support-CLOUDFLARE_ENV-in-wrangler branch 5 times, most recently from f7ca3ef to dfce7e7 Compare November 10, 2025 20:09

petebacondarwin marked this pull request as ready for review November 11, 2025 09:24

petebacondarwin commented Nov 11, 2025

View reviewed changes

ascorbic reviewed Nov 11, 2025

View reviewed changes

packages/workers-utils/src/config/validation.ts Outdated Show resolved Hide resolved

jamesopstad reviewed Nov 11, 2025

View reviewed changes

petebacondarwin force-pushed the pbd/support-CLOUDFLARE_ENV-in-wrangler branch from 7b99508 to 44af2c2 Compare November 11, 2025 15:56

petebacondarwin force-pushed the pbd/support-CLOUDFLARE_ENV-in-wrangler branch 2 times, most recently from fa8151a to b272db3 Compare November 14, 2025 09:26

petebacondarwin marked this pull request as draft November 14, 2025 10:21

petebacondarwin force-pushed the pbd/support-CLOUDFLARE_ENV-in-wrangler branch 2 times, most recently from 345ab79 to 194775d Compare November 24, 2025 12:16

petebacondarwin marked this pull request as ready for review November 24, 2025 13:08

petebacondarwin and others added 11 commits November 24, 2025 13:24

Make BundleController tests able to run on non-unix OSs

bda9bbc

ignore generated files from eslint

bd3d0ed

fix home directory mocking

1c77fa1

Improve isolation of containers push tests

aac260d

use logger.loggerLevel rather than recomputing it in Wrangler

3c43524

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/wo…

9583b37

…rkers-utils`

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

356cac9

fix "via" part of the validation error

d90efca

fixups after James' review

b3844d0

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

9014b9c

petebacondarwin force-pushed the pbd/support-CLOUDFLARE_ENV-in-wrangler branch from 194775d to 9014b9c Compare November 24, 2025 13:24

dario-piotrowicz approved these changes Nov 24, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Nov 24, 2025

fixups from Dario

f482fc4

petebacondarwin merged commit 43903a3 into main Nov 24, 2025
36 of 37 checks passed

github-project-automation bot moved this from Approved to Done in workers-sdk Nov 24, 2025

petebacondarwin deleted the pbd/support-CLOUDFLARE_ENV-in-wrangler branch November 24, 2025 17:37

workers-devprod mentioned this pull request Nov 24, 2025

Version Packages #11374

Merged

	const { getOutput } = await runWranglerDev(basePath, [
	await runWranglerDev(basePath, [

Conversation

petebacondarwin commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer Notes

Uh oh!

changeset-bot bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ascorbic commented Nov 10, 2025

Uh oh!

petebacondarwin commented Nov 10, 2025

Uh oh!

petebacondarwin Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jamesopstad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

petebacondarwin commented Nov 11, 2025

Uh oh!

dario-piotrowicz Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

petebacondarwin Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

dario-piotrowicz Nov 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

PetarMetodiev commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

petebacondarwin commented Nov 9, 2025 •

edited

Loading

changeset-bot bot commented Nov 9, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 9, 2025 •

edited

Loading