@astrojs/cloudflare doesn't correctly forward wrangler `vars` to Astro

[alexanderdombroski]

Astro Info

Astro                    v6.3.5
Vite                     v7.3.3
Node                     v24.11.0
System                   macOS (arm64)
Package Manager          npm
Output                   static
Adapter                  @astrojs/cloudflare (v13.5.2)
Integrations             none

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

No response

Describe the Bug

The cloudflare adapter isn't fully compatible with astro:env.

Cloudflare's import { env } from "cloudflare:workers" (useable in workerd runtimes) correctly loads vars from the wrangler.jsonc, and the adapter is supposed to forward that env object to be used in Astro's astro:env API. See cloudflare integration code. For some unknown reason, variables that originated from the wrangler.jsonc aren't forwarded.

See related issue discussing what should be expected behavior.

Workaround: Import the env object from "cloudflare:workers" instead of "astro:env", or make variables available during build time and use astro:env.

What's the expected result?

Environment variables defined in the vars field of wrangler.jsonc and env.schema of astro.config.mjs should be importable from "astro:env/client" or "astro:env/server".

Link to Minimal Reproducible Example

https://github.com/alexanderdombroski/astro-cloudflare-env

Participation

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

[astrobot-houston]

• Reproduced: Skipped — host-specific (requires Cloudflare workerd runtime)
• Exploration: Partial — reviewed the relevant adapter code paths
• Unit Test: No — reproduction requires Cloudflare's workerd runtime which is unavailable in our sandbox
• Priority: P2: Has Workaround. This affects users of @astrojs/cloudflare who define environment variables in wrangler.jsonc vars and access them via astro:env. The workaround is to import directly from cloudflare:workers instead.

The Cloudflare adapter calls setGetEnv(createGetEnv(globalEnv)) at the top of packages/integrations/cloudflare/src/utils/handler.ts (line 22), where globalEnv is imported from cloudflare:workers. The createGetEnv helper in packages/integrations/cloudflare/src/utils/env.ts wraps this object to look up keys and return string values. The reported issue is that vars defined in wrangler.jsonc are present on the cloudflare:workers env object at runtime but are not surfacing through astro:env/server or astro:env/client. This could be a timing issue (the top-level setGetEnv call runs before the cloudflare:workers env object is fully populated with vars), or the globalEnv from cloudflare:workers may behave differently from the per-request env parameter passed to the handle() function (which receives bindings including vars).

I wasn't able to find a fix, but I identified some areas that may be relevant. The key code is in packages/integrations/cloudflare/src/utils/handler.ts — specifically the top-level setGetEnv(createGetEnv(globalEnv)) call on line 22. A potential issue is that the top-level import { env } from 'cloudflare:workers' may not include vars from wrangler.jsonc at module evaluation time, while the per-request env parameter in the handle(request, env, context) function (line 43) likely does. Moving the setGetEnv call inside the handle() function to use the request-scoped env parameter instead of the top-level globalEnv may resolve the forwarding gap. The createGetEnv helper in packages/integrations/cloudflare/src/utils/env.ts itself looks correct — it properly handles string, boolean, and number values.

Full Triage Report

Triage Report: Issue #16790

Issue Details

• Title: @astrojs/cloudflare doesn't correctly forward wrangler vars to Astro
• URL: @astrojs/cloudflare doesn't correctly forward wrangler vars to Astro #16790
• Author: alexanderdombroski
• Created: 2026-05-19T14:20:28Z
• State: open
• Labels: needs triage

Environment (from issue)

• Astro v6.3.5
• Vite v7.3.3
• Node v24.11.0
• System: macOS (arm64)
• Package Manager: npm
• Output: static
• Adapter: @astrojs/cloudflare (v13.5.2)
• Integrations: none

Bug Description

The Cloudflare adapter (@astrojs/cloudflare) isn't fully compatible with astro:env. Specifically, environment variables defined in the vars field of wrangler.jsonc are not correctly forwarded to Astro's astro:env API (astro:env/client and astro:env/server).

Cloudflare's import { env } from "cloudflare:workers" correctly loads vars from wrangler.jsonc in workerd runtimes, and the adapter is supposed to forward that env object for use in Astro's astro:env API. The relevant adapter code is in packages/integrations/cloudflare/src/utils/handler.ts (line 22 in the linked commit). However, variables originating from wrangler.jsonc aren't being forwarded.

Expected Result

Environment variables defined in the vars field of wrangler.jsonc and env.schema of astro.config.mjs should be importable from astro:env/client or astro:env/server.

Workaround

Import the env object from cloudflare:workers instead of astro:env, or make variables available during build time and use astro:env.

Reproduction URL

https://github.com/alexanderdombroski/astro-cloudflare-env

Related Issue

withastro/docs#13897 (discussing expected behavior)

Reproduction Status: SKIPPED

Skip Reason: host-specific

This issue is specific to the Cloudflare hosting platform and its workerd runtime. Reproduction requires:

1. Cloudflare's workerd runtime — The cloudflare:workers module is only available in Cloudflare's runtime environment, not in Node.js.
2. wrangler CLI — The vars configuration in wrangler.jsonc is processed by Cloudflare's wrangler tool, which spins up a local workerd instance.
3. Cloudflare adapter runtime behavior — The bug is about how the adapter's request handler (handler.ts) forwards environment variables from Cloudflare's runtime env object to Astro's astro:env module at runtime, which only executes within the workerd context.

Our sandbox environment only supports Node.js and cannot simulate the Cloudflare workerd runtime, wrangler dev, or the cloudflare:workers module. This bug cannot be reproduced without the Cloudflare-specific runtime.

Key Code Reference

The reporter points to the handler code at packages/integrations/cloudflare/src/utils/handler.ts (line 22) as the relevant forwarding logic. This would be the starting point for diagnosis — examining how the adapter reads from cloudflare:workers env and passes it to Astro's env system.

Code Analysis

• handler.ts line 22: setGetEnv(createGetEnv(globalEnv)) — called at module top-level with the globalEnv imported from cloudflare:workers. This is the mechanism by which the Cloudflare adapter hooks into Astro's env system.
• env.ts (createGetEnv): Wraps the env object to return string values (converting booleans/numbers via .toString()). The logic itself appears correct.
• runtime.ts (setGetEnv): Replaces the internal _getEnv function used by astro:env to resolve variable values. Default falls back to process.env.
• Potential root cause: The top-level import { env } from 'cloudflare:workers' may not include vars from wrangler.jsonc at module evaluation time, while the per-request env parameter in handle(request, env, context) likely does. The setGetEnv call may need to be moved inside the request handler, or called again with the request-scoped env.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[alexanderdombroski]

I've narrowed down the issue more. It turns out getSecret is working in astro:env, so the issue is specifically with direct imports.

It seems packages/astro/src/env/runtime.ts and the cloudflare handler may be responsible for the getSecret functionality, and it seems to be working.

The handler doesn't seem to run at all in build, so moving the createGetEnv won't do much.

The files that look more-so responsible for creating direct environment variable imports are packages/astro/src/env/vite-plugin-env.ts and packages/astro/src/env/env-loader.ts. These rely on vite's loadEnv function. It pulls from process.env, but the wrangler vars must not be loaded yet. The validatePublicVariables seems to be the function pairs the schema up with the env list retrieved by vite.

Does this mean any adapter that doesn't put their environment variables in a file retrievable by vite—even if they implement astro:env and pass in vars to setGetEnv—they will only work using getSecret?

.dev.vars is picked up in a prerendered build because it is manually read in astro:config:done.

With these new findings, would it be better to just update documentation or code up another approach?

[thomas-callahan-collibra]

@alexanderdombroski I ran into this a while ago and started on a PR to fix it but I've never been able to get the tests to run successfully and have had other more pressing issues, so it's still in draft. The problem is that the Cloudflare adapter only loads vars from .env. It's been a while since I looked at this -- there's a note in the code saying to add .env support, but that already works for me -- maybe Wrangler's doing something to make the two equivalent somehow? Anyway I found where in Astro this happens and added the ability to load vars from the Wrangler config too (with the option to let .env override that). I'm not 100% sure it's the right solution for everybody though, and there may be a better way to do this, maybe using Vite loadEnv? As far as I know it hasn't been reviewed by anyone on the Astro team.

In the meantime, in my projects I converted that PR into an Astro plugin so that I could complete my Astro 6 migrations. This seems to work -- I've been using it in production on a coupe of sites for a month or so now. It loads the Wrangler file during initial Astro setup and extracts the vars from it.

One note -- the goal of this was to make the Wrangler config the source of truth in both local dev and the build and runtime phases in Cloudflare like it already is for runtime. That means you don't need to define vars in the build config in Cloudflare's dashboard or your local .env at all, except for any vars needed in your Astro config since (and all secrets). As a result, my build time vars in the Cloudflare dashboard only have like two things in them, while my project actually has about a dozen vars in use. (Side note: I wish Wrangler supported configuring build time vars in the config file!). It could be modified to only do this locally so that in CF you'd still use the vars defined in the dashboard.

It also assumes you're using a JSON or JSONC Wrangler config. Other formats could be made to work but you might need a library to support loading them. It also requires the strip-json-comments package, although this could be removed if you use JSON and not JSONC.

So you stick this in a JS/TS file somewhere:

import * as fs from "node:fs";
import type { AstroIntegration } from "astro";
import stripJsonComments from "strip-json-comments";

export default function loadVarsFromWranglerConfig(): AstroIntegration {
  return {
    name: "@thomascallahan/astro-cloudflare-load-vars-from-wrangler-config",
    hooks: {
      "astro:config:done": (params) => {
        const { config, logger } = params;
        // Assign wrangler.json or wrangler.jsonc's root vars property to process.env so astro:env can find these vars
        const wranglerConfigJSONPath = new URL("wrangler.json", config.root);
        const wranglerConfigJSONCPath = new URL("wrangler.jsonc", config.root);
        let resolvedWranglerConfigJSONPath;
        if (fs.existsSync(wranglerConfigJSONPath)) {
          resolvedWranglerConfigJSONPath = wranglerConfigJSONPath;
        } else if (fs.existsSync(wranglerConfigJSONCPath)) {
          resolvedWranglerConfigJSONPath = wranglerConfigJSONCPath;
        }
        if (resolvedWranglerConfigJSONPath) {
          console.log(
            "Loading wrangler.json/c from " + resolvedWranglerConfigJSONPath
          );
          try {
            const data = fs.readFileSync(
              resolvedWranglerConfigJSONPath,
              "utf-8"
            );
            const parsed = JSON.parse(stripJsonComments(data));
            const envName = process.env.CLOUDFLARE_ENV;
            console.log("Cloudflare environment:", envName);
            console.log(parsed);
            if (envName) {
              if (parsed.env?.[envName]?.vars) {
                console.log(
                  `Using vars from Cloudflare config environment "${process.env.CLOUDFLARE_ENV}"`
                );
                console.log(parsed.env[envName].vars);
                Object.assign(process.env, parsed.env[envName].vars);
              }
            } else {
              if (parsed.vars) {
                console.log(`Using vars from Cloudflare config root`);
                console.log(parsed.vars);
                Object.assign(process.env, parsed.vars);
              }
            }
            // console.log({ final_process_env: process.env });
          } catch (err: any) {
            logger.error(
              `Unable to parse wrangler.json/c, variables defined in it will not be available to your application.`
            );
            logger.error(err);
          }
        }
      },
    },
  };
}

then in astro.config.mjs:

import { loadVarsFromWranglerConfig } from "./wherever.js";

and:

export default defineConfig({
  adapter: cloudflare(),
  integrations: [
    loadVarsFromWranglerConfig(),
  ],
});

[matthewp]

@astrobot-houston triage — previous run was skipped due to workerd requirement. Please read the latest comments and try again.

[astrobot-houston]

• Reproduced: Yes — confirmed at build time: API_URL from wrangler.jsonc vars renders as undefined, PORT falls back to its default (4321) instead of the wrangler value (4322)
• Exploration: Yes — View branch
• Unit Test: Yes — updated test/astro-env.test.ts to remove the manual process.env overrides that were masking the bug
• Priority: P4: important. This violates the documented behavior of the Cloudflare adapter's astro:env integration. Users who define vars in wrangler.json/wrangler.jsonc (Cloudflare's standard approach) cannot use astro:env direct imports — only getSecret works. The workaround (importing from cloudflare:workers directly or duplicating vars in .env/.dev.vars) is functional but unintuitive.

The root cause is in packages/integrations/cloudflare/src/index.ts in the astro:config:done hook. The adapter reads .dev.vars into process.env so that astro:env's Vite plugin can find variables at build time, but it does not read vars from wrangler.json/wrangler.jsonc. Since astro:env public variables are inlined at build time via Vite's loadEnv() (which reads from process.env), wrangler config vars are invisible to direct imports. The existing test suite masked this bug by manually setting process.env.API_URL and process.env.PORT before building.

I found a potential fix for this issue. A new loadWranglerVars() utility parses vars from the wrangler JSON/JSONC config and assigns them to process.env in astro:config:done, before .dev.vars is loaded (so .dev.vars can override, matching wrangler's precedence). It supports CLOUDFLARE_ENV for environment-specific vars and the configPath adapter option. The existing test was updated to remove manual process.env overrides, and all 10 astro:env tests pass with the fix.

Try this fix

You can test this fix right now without waiting for a release:

npm i https://pkg.pr.new/@astrojs/cloudflare@5fb7b30

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Triage Report: Issue #16790

Issue Details

• Title: @astrojs/cloudflare doesn't correctly forward wrangler vars to Astro
• URL: @astrojs/cloudflare doesn't correctly forward wrangler vars to Astro #16790
• Author: alexanderdombroski
• Created: 2026-05-19T14:20:28Z
• State: open
• Labels: needs triage, triage: skipped

Environment (from issue)

• Astro v6.3.5
• Vite v7.3.3
• Node v24.11.0
• System: macOS (arm64)
• Package Manager: npm
• Output: static
• Adapter: @astrojs/cloudflare (v13.5.2)

Bug Description

The Cloudflare adapter isn't fully compatible with astro:env. Variables defined in wrangler.json/wrangler.jsonc vars are not available through astro:env/client or astro:env/server direct imports, though getSecret works correctly.

Reproduction

Built the existing test/fixtures/astro-env/ fixture without manually setting process.env.API_URL or process.env.PORT (which the existing test was doing to mask the bug). The wrangler.jsonc defines:

{
  "vars": {
    "API_URL": "https://google.de",
    "PORT": 4322
  }
}

Build output before fix:

• API_URL → ${void 0} (undefined) in the page template
• PORT → var PORT = 4321 (default value, not 4322)
• API_SECRET → works via getSecret runtime path ✓

Build output after fix:

• API_URL → var API_URL = "https://google.de" ✓
• PORT → var PORT = 4322 ✓
• API_SECRET → works via getSecret runtime path ✓

Root Cause

In packages/integrations/cloudflare/src/index.ts, the astro:config:done hook reads .dev.vars into process.env (line ~460) but does NOT read vars from wrangler.json/wrangler.jsonc. The astro:env system uses Vite's loadEnv() which reads from process.env and .env files to resolve public variable values at build time. Since wrangler config vars aren't in process.env, they're missing from the build.

The getSecret path works because it defers to runtime via setGetEnv(createGetEnv(globalEnv)) in handler.ts, where the Cloudflare cloudflare:workers env object has all vars. But direct imports (public vars) are inlined at build time and need to be in process.env.

The existing test (test/astro-env.test.ts) masked this bug by manually setting process.env.API_URL = 'https://google.de' and process.env.PORT = '4322' before building.

Fix

Files changed:

1. packages/integrations/cloudflare/src/utils/wrangler-config.ts (new) — loadWranglerVars() utility that:

   • Resolves the wrangler config path (wrangler.json → wrangler.jsonc, or custom configPath)
   • Strips JSONC comments (without adding a dependency)
   • Extracts vars (with CLOUDFLARE_ENV support for environment-specific vars)
   • Converts values to strings for process.env compatibility

2. packages/integrations/cloudflare/src/index.ts — Calls loadWranglerVars() in astro:config:done before .dev.vars loading, so .dev.vars can override wrangler vars (matching wrangler's own precedence).

3. packages/integrations/cloudflare/test/astro-env.test.ts — Removed manual process.env overrides; the test now relies on the adapter loading vars from wrangler.jsonc automatically.

Test results: All 10 astro:env tests pass (5 SSR + 5 dev).

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.