Improve DX for Cloudflare Worker Enviroments

[asdfjkalsdfla]

Astro Info

Astro                    v6.0.4
Node                     v24.13.1
System                   macOS (arm64)
Package Manager          pnpm
Output                   static
Adapter                  @astrojs/cloudflare
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

n/a

Describe the Bug

Astro v6's Cloudflare adapter doesn't support environments and drops all environment specific settings.

In my project, I have a dev, staging, and prod environment. Each one has a unique route and KV store to back it. When I deploy, only the global values are being used even when I specify the environment. For example, I run pnpm wrangler deploy --env staging. I noticed that the generated wrangler.json file in dist/server/ doesn't include any of the environment settings from the original wrangler.jsonc file. It also has definedEnvironments so the deploy doesn't fail when running the deploy. This could cause accidental deployments depending on the setup.

What's the expected result?

I should be able to specify unique cloudflare environments and have them use unique URLs, etc....

Link to Minimal Reproducible Example

https://github.com/asdfjkalsdfla/astro-callous-chroma

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

I was able to reproduce this issue. The generated dist/server/wrangler.json does not include the env sections from the source wrangler.jsonc. This is because @cloudflare/vite-plugin (which powers the Astro Cloudflare adapter) uses wrangler's unstable_readConfig() to produce a "pre-resolved" flat config for a single environment — the env object is resolved/merged at read time and never carried into the output. The output includes definedEnvironments: ["staging", "dev"] as metadata but no actual environment-specific settings, so deploying with wrangler deploy --env staging uses only the global config values.

I was unable to find a fix for this issue. This behavior originates in @cloudflare/vite-plugin and wrangler's config resolution, not in Astro's Cloudflare adapter itself. The Astro adapter (packages/integrations/cloudflare/src/index.ts) passes through to @cloudflare/vite-plugin without any environment processing. As a workaround, you can set the CLOUDFLARE_ENV environment variable at build time (e.g., CLOUDFLARE_ENV=staging astro build) — this causes the vite plugin to resolve the correct environment's settings into the flat output config. The tradeoff is that you need a separate build per environment. This limitation should likely be reported upstream to @cloudflare/vite-plugin as a feature request for multi-environment output support.

P2: has workaround. Users with multiple Cloudflare environments (dev/staging/prod) with environment-specific bindings are affected. The workaround of setting CLOUDFLARE_ENV at build time works correctly (verified: the output wrangler.json includes targetEnvironment and the correct environment-specific KV IDs), but requires separate builds per environment rather than a single build deployed to multiple environments.

Full Triage Report

Reproduction

Cloned the minimal reproduction at https://github.com/asdfjkalsdfla/astro-callous-chroma and ran astro build.

Source wrangler.jsonc contains:

• Global KV namespace with id: "<GLOBAL_KV_ID>"
• env.staging with KV namespace id: "<STAGING_KV_ID>"
• env.dev with KV namespace id: "<DEV_KV_ID>"

Output dist/server/wrangler.json contains:

• "definedEnvironments": ["staging", "dev"] (metadata only)
• "kv_namespaces": [{"binding": "SESSION"}, {"binding": "<MY_NAMESPACE>", "id": "<GLOBAL_KV_ID>"}]
• No env section at all
• No environment-specific KV IDs

This confirms the bug: environment-specific settings are dropped from the output.

Diagnosis

The root cause is in the config resolution pipeline, not in the Astro adapter:

1. @cloudflare/vite-plugin calls wrangler.unstable_readConfig({ config: configPath, env: cloudflareEnv }) during build
2. Wrangler's unstable_readConfig reads the raw config, extracts definedEnvironments = Object.keys(rawConfig.env ?? {}), then merges the specified environment (if any) into a flat top-level config. The env object is consumed and discarded.
3. The vite plugin's outputConfigPlugin takes this flat resolved config and writes it to dist/server/wrangler.json via JSON.stringify()
4. The CLOUDFLARE_ENV environment variable controls which environment gets resolved. If not set, no environment merging occurs — only global settings are used.

Key files:

• packages/integrations/cloudflare/src/index.ts:214 — passes options to cfVitePlugin()
• packages/integrations/cloudflare/src/wrangler.ts — only adds default bindings (SESSION, IMAGES, ASSETS), does not process environments
• The environment flattening logic lives entirely in @cloudflare/vite-plugin and wrangler internals

Workaround Verification

Building with CLOUDFLARE_ENV=staging produces a correct output:

• "targetEnvironment": "staging"
• "name": "staging"
• "kv_namespaces": [{"binding": "SESSION"}, {"binding": "<MY_NAMESPACE>", "id": "<STAGING_KV_ID>"}]

The staging-specific KV ID is correctly resolved. However, this requires a separate build per environment.

Verdict

This is a limitation of @cloudflare/vite-plugin (and wrangler's redirected config model) rather than a bug in the Astro Cloudflare adapter specifically. The Astro adapter correctly delegates to the vite plugin but has no mechanism to preserve or forward multi-environment configs. The upstream plugin intentionally produces a single-environment flat config, which is a design choice that doesn't support the traditional wrangler workflow of "build once, deploy to many environments."

This report was made by an LLM. Mistakes happen, check important info.

[alexiglesias93]

+1 this happened to us as well, this deploy command in the worker's build configuration was working fine in v5:
npx wrangler deploy --env production
But in v6 the deployed environment is not respecting the --env flag.

Following astrobot's suggestion to add a CLOUDFLARE_ENV build variable fixed the issue:

[asdfjkalsdfla]

While this one has a workaround, it could cause an issue as people wouldn't expect the change in behavior/doesn't break. I'd make this one an important fix based on that.

cc: @matthewp

[alexanderniebuhr]

We are waiting for feedback from the Cloudflare team. Additionally Cloudflare's own documentation say to use the CLOUDFLARE_ENV solution.

[alexanderniebuhr]

Okay after consulting with Cloudflare team this is actually a limitation of their vite plugin. You can find all the information in their docs:

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
https://developers.cloudflare.com/changelog/post/2025-11-09-cloudflare-env-variable/#use-with-build-tools

With the Cloudflare Vite plugin, Cloudflare Environments are applied at dev and build time. Running wrangler deploy --env some-env is therefore not applicable and the environment to deploy should instead be set by running CLOUDFLARE_ENV=some-env vite build.
https://developers.cloudflare.com/workers/vite-plugin/reference/migrating-from-wrangler-dev/#cloudflare-environments

https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/

Please open an issue in the upstream repository https://github.com/cloudflare/workers-sdk

[asdfjkalsdfla]

In the very least, this should be included in the migration documentation as this is a significant change in behavior that could result in accidental deployments. I also think it should intentionally break the deploy to prevent deploying code to the wrong environment.