astro/cloudflare doesn't use environment vars specified in wrangler config or adhere to CLOUDFLARE_ENV when running/building

[calumpeak]

Astro Info

Astro                    v5.14.5
Node                     v24.7.0
System                   macOS (arm64)
Package Manager          npm
Output                   server
Adapter                  @astrojs/cloudflare

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

No response

Describe the Bug

Possible regression

I set .env.development and .env.production to contain CLOUDFLARE_ENV=dev and CLOUDFLARE_ENV=prod to utilise the env variables specified in my wrangler.jsonc { env: { dev: { vars: {... however when running astro with the cloudflare plugin it no longer picks up the variables in my wrangler config and I have to duplicate them into .env.development and .env.production to build the application.

This error appears
The following environment variables defined in env.schema are invalid:

(my example doesn't throw an error, just doesn't render the environment variable)

What's the expected result?

Cloudflare plugin should respect CLOUDFLARE_ENV as per https://developers.cloudflare.com/workers/vite-plugin/reference/cloudflare-environments/#combining-cloudflare-environments-and-vite-modes

It should utilise vars from the matching wrangler variable namespace and load those into the application based upon CLOUDFLARE_ENV setting and mode.

Link to Minimal Reproducible Example

https://github.com/calumpeak/env-repro

Participation

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

[rickmoens]

You can include the --env <environment> or -e <environment> flag to select the environment, see: Configuring different environments in Wrangler.

So for your project you can:

• Dev: wrangler dev --env dev > env.API_KEY ("dev")
• Prod: wrangler dev --env prod > env.API_KEY ("prod")

[matthewp]

@calumpeak does this solve your problem?

[calumpeak]

@matthewp Nope, I tried this every which way prior to opening the ticket including @rickmoens method - I need astro to build with the correct environment variables prior to running wrangler in the first place as it needs to create the dist files.

[wuzzeb]

I've been facing perhaps the same problem with .env.development and environment variable mismatch, and I eventually found the problem which perhaps can help you. The issue is a mismatch between the astro mode and the wrangler environment. The default astro mode is called "development" but the default wrangler env is just called "dev". This leads to a very confusing mismatch:

• In static (prerender = true), import.meta.env will load from the astro mode
• In server (prerender = false), import.meta.env will load from the wrangler mode
• Astro.locals.runtime.env will load from the wrangler env in all situations. For prerender = true, this gives a very weird situation where import.meta.env will be different than Astro.locals.runtime.env (this is what took so long to find, since I never expected import.meta.env and Astro.locals.runtime.env to be different.)

To see this, create files such as

.env.development

PUBLIC_AAA=apples

.env.staging

PUBLIC_AAA=pears

and then in astro.config.ts make the wrangler mode "staging"

adapter: [cloudflare({
    platformProxy: {
      environment: "staging",
    },
})],

and then create a small page

index.page

---
import Layout from "../layouts/Layout.astro";
console.log(Astro.locals.runtime.env);
console.log(import.meta.env);
export const prerender = true;
---

<Layout>
  <div>
    <pre>
      {JSON.stringify(import.meta.env, undefined, 2)}
    </pre>
  </div>
</Layout>

Then run

astro dev

In this case, Astro.locals.runtime.env will contain PUBLIC_AAA=pears because it loaded from the staging .env. But, import.meta.env will contain PUBLIC_AAA=apples and also import.meta.env will have MODE=development. This is both in the console and on the page.

If you instead run

astro dev --mode staging

then you will only see PUBLIC_AAA=pears in all situations (and import.meta.env.MODE = staging).

The way I worked around this issue is to always ensure the astro mode and wrangler mode match but that is hard because you need to hard-code the wrangler mode into the platformProxy.environment variable.

Changes

I think the cloudflare adapter should just always ensure the astro mode and platformProxy.environment match. That is, platformProxy.environment should default to whatever the astro mode is. The problem may be introducing this may cause a backwards incompatibility, so perhaps something like

adapter: cloudflare({
  platformProxy: {
    environmentFromAstroMode: true
  }
})

[michrome]

I'm trying to use Cloudflare Hyperdrive with Astro. For local development, it works if I define localConnectionString in wrangler.jsonc but I don't want to do that because I don't want to commit my local database credentials.

Instead, I want to define CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING-NAME> in my .env. Unfortunately wrangler(?) isn't reading the environment so thows the error shown below.

I believe this is related to this issue and I believe it is fixed with this PR.

I don't know how to bring that fix into @astrojs/cloudflare but hopefully this comment helps someone who does. 🙏

16:06:53 [ERROR] [@astrojs/cloudflare] An unhandled error occurred while running the "astro:server:setup" hook
When developing locally, you should use a local Postgres connection string to emulate Hyperdrive functionality. Please setup Postgres locally and set the value of the 'CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE' variable or "HYPERDRIVE"'s "localConnectionString" to the Postgres connection string.

[florian-lefebvre]

So do I understand correctly there's a mismatch between Astro/Vite development mode and wrangler dev environment. Is that really an Astro issue though? You could rename your wrangler environment to development and that should work? That being said, maybe we can improve the docs and log a warning if we detect a mismatch

[wuzzeb]

Yeah, as long as you make sure to keep the vite mode and wrangler env the same, it works. I do exactly that, naming the wrangler environments "development", "staging", "production" and then in package.json, I have commands

"scripts": {
  "dev": "CLOUDFLARE_ENV=development astro dev --mode development"
  "build:staging": "CLOUDFLARE_ENV=staging astro build --mode staging"
  "build:production": "CLOUDFLARE_ENV=production astro build --mode production"
}

and then in astro.config.ts I have

  adapter: cloudflare({
    platformProxy: {
      environment: process.env.CLOUDFLARE_ENV,
    },
  }),

I think a doc update and a warning in the console would be a great idea.