From e5b2022701f55fc7f932eab24ef5d67b68050f09 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sun, 9 Nov 2025 15:32:34 +0000 Subject: [PATCH 1/3] 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 https://github.com/cloudflare/workers-sdk/pull/11228 Co-Authored-By: pbacondarwin@cloudflare.com --- .../2025-11-09-cloudflare-env-variable.mdx | 47 +++++++++++++++++++ .../docs/workers/wrangler/environments.mdx | 2 + .../wrangler/system-environment-variables.mdx | 4 ++ 3 files changed, 53 insertions(+) create mode 100644 src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx diff --git a/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx b/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx new file mode 100644 index 000000000000000..404e8d4bbe68d54 --- /dev/null +++ b/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx @@ -0,0 +1,47 @@ +--- +title: Select Wrangler environments using the CLOUDFLARE_ENV environment variable +description: Wrangler now supports the CLOUDFLARE_ENV environment variable to select the active environment without using the --env flag. +products: + - workers +date: 2025-11-09 +--- + +Wrangler now supports using the `CLOUDFLARE_ENV` [environment variable](/workers/wrangler/system-environment-variables/#supported-environment-variables) to select the active [environment](/workers/wrangler/environments/) for your Worker commands. This provides a more flexible way to manage environments, especially when working with build tools and CI/CD pipelines. + +## What's new + +**Environment selection via environment variable:** +- Set `CLOUDFLARE_ENV` to specify which environment to use for Wrangler commands +- Works with all Wrangler commands that support the `--env` flag +- The `--env` command line argument takes precedence over the `CLOUDFLARE_ENV` environment variable + +## Example usage + +```bash +# Deploy to the production environment using CLOUDFLARE_ENV +CLOUDFLARE_ENV=production wrangler deploy + +# Upload a version to the staging environment +CLOUDFLARE_ENV=staging wrangler versions upload + +# The --env flag takes precedence over CLOUDFLARE_ENV +CLOUDFLARE_ENV=dev wrangler deploy --env production +# This will deploy to production, not dev +``` + +## Use with build tools + +The `CLOUDFLARE_ENV` environment variable is particularly useful when working with build tools like Vite. You can set the environment once during the build process, and it will be used for both building and deploying your Worker: + +```bash +# Set the environment for both build and deploy +CLOUDFLARE_ENV=production npm run build +CLOUDFLARE_ENV=production wrangler deploy +``` + +When using `@cloudflare/vite-plugin`, the build process generates a "redirected deploy config" that is flattened to only contain the active environment. Wrangler will validate that the environment specified matches the environment used during the build to prevent accidentally deploying a Worker built for one environment to a different environment. + +## Learn more + +- [System environment variables](/workers/wrangler/system-environment-variables/) +- [Environments](/workers/wrangler/environments/) diff --git a/src/content/docs/workers/wrangler/environments.mdx b/src/content/docs/workers/wrangler/environments.mdx index 9c1ce25a78f53ae..788f0e4663b782e 100644 --- a/src/content/docs/workers/wrangler/environments.mdx +++ b/src/content/docs/workers/wrangler/environments.mdx @@ -48,6 +48,8 @@ Review the following environments flow: 4. Environments are used with the `--env` or `-e` flag on Wrangler commands. For example, you can develop the Worker in the `dev` environment by running `npx wrangler dev -e=dev`, and deploy it with `npx wrangler deploy -e=dev`. + Alternatively, you can use the [`CLOUDFLARE_ENV` environment variable](/workers/wrangler/system-environment-variables/#supported-environment-variables) to select the active environment. For example, `CLOUDFLARE_ENV=dev npx wrangler deploy` will deploy to the `dev` environment. The `--env` command line argument takes precedence over the `CLOUDFLARE_ENV` environment variable. + diff --git a/src/content/docs/workers/wrangler/system-environment-variables.mdx b/src/content/docs/workers/wrangler/system-environment-variables.mdx index c24339d23823ffd..9ae60d873f950fa 100644 --- a/src/content/docs/workers/wrangler/system-environment-variables.mdx +++ b/src/content/docs/workers/wrangler/system-environment-variables.mdx @@ -51,6 +51,10 @@ Wrangler supports the following environment variables: - The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`. +- `CLOUDFLARE_ENV` + + - The [environment](/workers/wrangler/environments/) to use for Wrangler commands. This allows you to select an environment without using the `--env` flag. For example, `CLOUDFLARE_ENV=production wrangler deploy` will deploy to the `production` environment. The `--env` command line argument takes precedence over this environment variable. + - `WRANGLER_SEND_METRICS` - Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md). From 6014eacf28178e71b1ebf2eed64895b3204663d4 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Sun, 9 Nov 2025 15:53:36 +0000 Subject: [PATCH 2/3] Update changelog to combine build and deploy commands with & Co-Authored-By: pbacondarwin@cloudflare.com --- .../changelog/workers/2025-11-09-cloudflare-env-variable.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx b/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx index 404e8d4bbe68d54..c6581b8c6896b47 100644 --- a/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx +++ b/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx @@ -35,8 +35,7 @@ The `CLOUDFLARE_ENV` environment variable is particularly useful when working wi ```bash # Set the environment for both build and deploy -CLOUDFLARE_ENV=production npm run build -CLOUDFLARE_ENV=production wrangler deploy +CLOUDFLARE_ENV=production npm run build & wrangler deploy ``` When using `@cloudflare/vite-plugin`, the build process generates a "redirected deploy config" that is flattened to only contain the active environment. Wrangler will validate that the environment specified matches the environment used during the build to prevent accidentally deploying a Worker built for one environment to a different environment. From 60d164226654e2440dbc46f88affcc37b13e91fd Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Mon, 10 Nov 2025 12:55:35 +0000 Subject: [PATCH 3/3] Add link to generated wrangler configuration docs in changelog Co-Authored-By: pbacondarwin@cloudflare.com --- .../changelog/workers/2025-11-09-cloudflare-env-variable.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx b/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx index c6581b8c6896b47..f405d7512be43a7 100644 --- a/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx +++ b/src/content/changelog/workers/2025-11-09-cloudflare-env-variable.mdx @@ -38,7 +38,7 @@ The `CLOUDFLARE_ENV` environment variable is particularly useful when working wi CLOUDFLARE_ENV=production npm run build & wrangler deploy ``` -When using `@cloudflare/vite-plugin`, the build process generates a "redirected deploy config" that is flattened to only contain the active environment. Wrangler will validate that the environment specified matches the environment used during the build to prevent accidentally deploying a Worker built for one environment to a different environment. +When using `@cloudflare/vite-plugin`, the build process generates a ["redirected deploy config"](/workers/wrangler/configuration/#generated-wrangler-configuration) that is flattened to only contain the active environment. Wrangler will validate that the environment specified matches the environment used during the build to prevent accidentally deploying a Worker built for one environment to a different environment. ## Learn more