`@astrojs/cloudflare`: `astro build --env <name>` does not pass wrangler environment to `@cloudflare/vite-plugin`

[F0rce]

Astro Info

Astro                    v6.0.8
Vite                     v7.3.1
Node                     v24.7.0
System                   macOS (arm64)
Package Manager          pnpm
Output                   server
Adapter                  @astrojs/cloudflare (v13.1.3)
Integrations             @storyblok/astro (v8.1.0)

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

No response

Describe the Bug

When using wrangler environment-specific config (env.staging in wrangler.jsonc) and building with astro build --env staging, the generated dist/server/wrangler.json always contains the top-level config values instead of the environment-specific ones. This means account_id, route, name, assets, and other env-overridden fields are incorrect in the build output.

Running wrangler deploy --env staging after the build then either deploys to the wrong account or fails due to mismatched config.

Root Cause

The @cloudflare/vite-plugin determines which wrangler environment to use via the CLOUDFLARE_ENV environment variable, loaded through vite.loadEnv():

// @cloudflare/vite-plugin/dist/index.mjs
const prefixedEnv = vite.loadEnv(viteEnv.mode, root, ["CLOUDFLARE_", ...]);
const cloudflareEnv = prefixedEnv.CLOUDFLARE_ENV;

@astrojs/cloudflare never sets or forwards CLOUDFLARE_ENV. Astro's --env flag is not propagated to the Cloudflare vite plugin, so unstable_readConfig is called with env: undefined, resolving to the top-level config.

Reproduction

wrangler.jsonc:

{
  "account_id": "production-account-id",
  "name": "my-app",
  "env": {
    "staging": {
      "account_id": "staging-account-id",
      "name": "my-app-staging",
      "route": {
        "pattern": "staging.example.com",
        "custom_domain": true
      }
    }
  }
}

Build command:

astro build --env staging

Result in dist/server/wrangler.json:

{
  "account_id": "production-account-id",
  "name": "my-app",
  "route": { "pattern": "production.example.com", "custom_domain": true }
}

Expected in dist/server/wrangler.json:

{
  "account_id": "staging-account-id",
  "name": "my-app-staging",
  "targetEnvironment": "staging",
  "route": { "pattern": "staging.example.com", "custom_domain": true }
}

Workaround

Manually set CLOUDFLARE_ENV as an environment variable before building:

CLOUDFLARE_ENV=staging astro build --env staging

This correctly resolves the wrangler environment config and produces the expected output.

What's the expected result?

@astrojs/cloudflare should forward Astro's --env value to CLOUDFLARE_ENV (or pass it directly to the @cloudflare/vite-plugin config) so that wrangler.unstable_readConfig resolves the correct environment.

Link to Minimal Reproducible Example

https://github.com/F0rce/astro-cloudflare-env-bug

Participation

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

[astrobot-houston]

I was able to reproduce this issue. When building without CLOUDFLARE_ENV set, the generated dist/server/wrangler.json always contains the top-level wrangler config values instead of environment-specific ones (e.g., account_id, name, route all resolve to top-level). However, it's important to note that astro build --env staging is not a valid Astro CLI flag — Astro's build command supports --outDir, --mode, --devOutput, --force, and --help, but not --env. The flag is silently ignored by the argument parser. The core issue is that @astrojs/cloudflare has no mechanism to forward a wrangler environment name to @cloudflare/vite-plugin.

I was unable to find a fix for this issue. This is more accurately a feature request than a bug — @astrojs/cloudflare was never designed to forward wrangler environments, and @cloudflare/vite-plugin has no programmatic env option in its PluginConfig type. The only supported mechanism is the CLOUDFLARE_ENV environment variable. The workaround documented in the issue is correct and is the intended approach: CLOUDFLARE_ENV=staging astro build. Alternatively, you can create a .env.staging file with CLOUDFLARE_ENV=staging and build with astro build --mode staging. A potential enhancement would be for @astrojs/cloudflare to add a cloudflareEnv option that sets process.env.CLOUDFLARE_ENV before the Vite plugin initializes.

P2: has workaround. This affects users with multi-environment Cloudflare deployments using env.<name> sections in wrangler.jsonc. The workaround (CLOUDFLARE_ENV=staging astro build) is trivial and well-documented, requiring only a single environment variable prefix to the build command.

Full Triage Report

Issue Details

Title: @astrojs/cloudflare: astro build --env <name> does not pass wrangler environment to @cloudflare/vite-plugin
Author: F0rce
URL: #16031

Environment

• Astro: v6.0.8 (reporter) / local monorepo HEAD (reproduction)
• @astrojs/cloudflare: v13.1.3
• @cloudflare/vite-plugin: ^1.25.6
• Node.js: v24.7.0 (reporter) / local (reproduction)

Reproduction

Setup

Reproduction used a wrangler.jsonc with:

• Top-level: account_id: "top-level-account-id", name: "repro-app", assets.not_found_handling: "none"
• env.staging: account_id: "staging-account-id", name: "repro-app-staging", assets.not_found_handling: "single-page-application"

Test 1: Build without CLOUDFLARE_ENV (bug confirmed)

Command: astro build

Result in dist/server/wrangler.json:

• account_id: "top-level-account-id" (top-level, NOT staging)
• name: "repro-app" (top-level, NOT staging)
• No targetEnvironment field

Test 2: Build with --env staging flag

Command: astro build --env staging

Result: The --env flag does NOT exist in Astro's CLI. It is silently ignored by yargs-parser. Output is identical to Test 1.

Test 3: Build with CLOUDFLARE_ENV env var (workaround)

Command: CLOUDFLARE_ENV=staging astro build

Result in dist/server/wrangler.json:

• account_id: "staging-account-id" ✅ (staging)
• name: "repro-app-staging" ✅ (staging)
• targetEnvironment: "staging" ✅ (present)

Root Cause Analysis

Classification: Feature Request (not a bug in existing behavior)

1. --env is not an Astro CLI flag — The flagsToAstroInlineConfig() function in packages/astro/src/cli/flags.ts only maps known flags (--config, --mode, --root, --site, --base, --outDir, --port, --host, --open, --allowedHosts). The astro build help text explicitly lists supported flags: --outDir, --mode, --devOutput, --force, --help.

2. @cloudflare/vite-plugin reads CLOUDFLARE_ENV from environment — The plugin calls vite.loadEnv(viteEnv.mode, root, ["CLOUDFLARE_", ...]) during config resolution. It reads prefixedEnv.CLOUDFLARE_ENV and passes it as env to resolveWorkerConfig(). If not set, env is undefined and top-level wrangler config is used.

3. @astrojs/cloudflare never sets CLOUDFLARE_ENV — The integration's Options interface has no env or cloudflareEnv option. Additionally, the PluginConfig type from @cloudflare/vite-plugin has no programmatic env property — the only mechanism is the CLOUDFLARE_ENV environment variable.

Code Path

1. User runs astro build --env staging
2. yargs-parser parses {env: "staging"} but this is silently ignored by flagsToAstroInlineConfig()
3. cfVitePlugin({...}) is called at packages/integrations/cloudflare/src/index.ts:214 without any env info
4. @cloudflare/vite-plugin reads CLOUDFLARE_ENV from env → undefined
5. resolveWorkerConfig() called with env: undefined → top-level wrangler config used

Workarounds

1. Environment variable: CLOUDFLARE_ENV=staging astro build
2. Vite .env file: Create .env.staging with CLOUDFLARE_ENV=staging, then build with astro build --mode staging

Suggested Enhancement

Add a cloudflareEnv option to @astrojs/cloudflare's Options interface that sets process.env.CLOUDFLARE_ENV before the Vite plugin initializes. This would improve DX for multi-environment Cloudflare deployments.

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

[F0rce]

Hey! After digging deeper into this, I want to reclassify — this is more of a feature request than a bug.

I realized that --env is not actually an Astro CLI flag (it was silently ignored by yargs-parser), and @cloudflare/vite-plugin's PluginConfig doesn't expose a programmatic env option — the only mechanism is the CLOUDFLARE_ENV environment variable.

The workaround (CLOUDFLARE_ENV=staging astro build) works, but it's not great from a DX perspective — especially when you want to configure things programmatically in astro.config.ts rather than relying on env vars in build scripts.

I'd love to discuss whether it would make sense to add a cloudflareEnv option to the @astrojs/cloudflare adapter:

// astro.config.ts
export default defineConfig({
  adapter: cloudflare({
    cloudflareEnv: isStaging ? 'staging' : undefined,
  }),
});

Under the hood this would simply set process.env.CLOUDFLARE_ENV before @cloudflare/vite-plugin initializes. Small change, but it would make multi-environment Cloudflare deployments much more ergonomic and discoverable — rather than having users figure out that they need a specific env var that isn't documented anywhere in the Astro docs.

I've prototyped this in a fork (branch) and can open a PR if there's interest.

[alexanderniebuhr]

@F0rce thanks for report. I agree we should find a better way to do this. I'll ask the Cloudflare team if it makes sense to add a config option to PluginConfig first.

[lifeforcedev]

For me the missing piece was that platformProxy.environment must read CLOUDFLARE_ENV and that value must match the [env.<name>] section in wrangler.toml. Added docs here: withastro/docs#13995