Misleading Cloudflare environment variables section

[alexanderdombroski]

📚 Subject area/topic

Cloudflare Environment Variables

📋 Page(s) affected (or suggested, for new content)

Page: https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-bindings
Filepath: src/content/docs/en/guides/integrations-guide/cloudflare.mdx

📋 Description of content that is out-of-date or incorrect

Background

When using the Cloudflare adapter, I've learned I can use environment variables in 4 ways.

1. using import.meta.env.*
2. using imports from "astro:env/client" or "astro:env/server"
3. using the env object imported from "cloudflare:workers"
4. using process.env.*

From my understanding, the first two are Astro's type-safe system and second two are Cloudflare's (also type-safe) system.

The Confusing Part

In the cloudflare adapter guide, the sentence "They are also compatible with the astro:env API" is unclear.

Cloudflare environment variables defined in .dev.vars, wrangler.jsonc or the cloudflare dashboard can NOT be imported from astro:env/server.

Is the documentation only suggesting that I can use both environment variable systems in the same application? Or is it that the APIs are connected and can be mixed? It should be clearly stated that these two systems are separate and when either is preferable.

[ArmandPhilippot]

From my understanding, this should work.

The Cloudflare docs says environment variables are available from import { env } from "cloudflare:workers"; and the integration uses that to pass them to astro:env.

Digging a little, I wonder if this could be related to withastro/astro#14540 It seems Cloudflare doesn't use the same name as Vite for the dev environment, so it's possible that the variables aren't being transmitted correctly and you need to rename the Cloudflare dev environment?

A minimal repro would be helpful to determine if this is really a documentation issue or rather a bug.

using import.meta.env.*
using imports from "astro:env/client" or "astro:env/server"
using the env object imported from "cloudflare:workers"
using process.env.*

From my understanding, the first two are Astro's type-safe system and second two are Cloudflare's (also type-safe) system.

To be clear:

• import.meta.env comes from Vite (Astro is built on top of Vite)
• astro:env is specific to Astro (but this should be compatible with the different adapters)
• cloudflare:workers is specific to Cloudflare
• process.env is not specific to Cloudflare, this is a Node API and can be used with Astro even if astro:env is the preferred way.

But, anyway, you should be able to use astro:env with Cloudflare.

[alexanderdombroski]

Hi Armand, thanks for the detail of your response.

I see my confusion now. I was using an endpoint and my variable was set to private server and was stripped out of the bundle. I got confused because I could see it locally by logging process.env.

I still don't believe Cloudflare is fully compatible with astro:env, though. Can I get further clarification on expected behavior?

• Should the vars field of wrangler.jsonc be importable from astro:env? I couldn't get the vite & cloudflare environment modes to line up like as suggested in the closed issue you shared. A solution should be added to the documentation, or the vars field of the wrangler config should be noted as not fully compatible with astro:env in the astro cloudflare adapter documentation
• Unrelated to Cloudflare—Is bundling of secret astro:env/server vars only prevented in production builds, or should they be in the dev environment too? Are they only meant to be used in SSG? Not sure how they’re meant to be used on the server if they’re completely stripped from the bundle

I did much more testing to fully understand Astro's behavior in this github repo. It should cover every edge case, except cloudflare-environment specific configuration. Hope its helpful!

[ArmandPhilippot]

Thanks for the repo. Yeah, I can see something seems wrong with wrangler.jsonc... But I'm not a Cloudflare user so I cannot say anything with certainty.

Should the vars field of wrangler.jsonc be importable from astro:env?

It seems to me this should work and it's worth opening an issue in withastro/astro.

Is bundling of secret astro:env/server vars only prevented in production builds, or should they be in the dev environment too? Are they only meant to be used in SSG? Not sure how they’re meant to be used on the server if they’re completely stripped from the bundle

Unlike public variables, secrets are not inlined in the production build which means you need to provide them when starting the production server. I don't know exactly how this is implemented but, instead of having the raw value in the bundle, a platform specific getter will be used to retrieve the secret.

I'm not sure how this works with Cloudflare as I'm not a Cloudflare user. I think you only need to configure them in your dashboard.

But, for example, with Node you can provide them in the command line with DB_PASSWORD="my secret" node ./dist/server/entry.mjs (obviously, this is not ideal for a secret this is just an example 😄 ). And, in the bundle, you probably get process.env.DB_PASSWORD instead of my secret.

And, from your repo:

import.meta.env.DEV works, but environment variables aren't attached.

import.meta.env.MY_VARIABLE won't work inside public scripts unless you prefix it with PUBLIC_.

[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: #13995