Environment Variables for integrations can be handled different than Astro

[chexxor]

📚 Subject area/topic

environment variables

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

https://docs.astro.build/en/guides/environment-variables/
https://docs.astro.build/en/guides/integrations-guide/cloudflare/#cloudflare-runtime

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

The Astro docs say that the environment variables can be set using a .env file. Cloudflare and its Wrangler tool use .dev.vars instead if that one.

The Astro docs say that environment variables can be read using the import.meta.env object. When running on Cloudflare, however, the Cloudflare integration places them on the Astro.locals.runtime.env object, or the context.locals.runtime.env object in endpoints.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[sarah11918]

Thanks for filing this issue! I'll ask @florian-lefebvre to have a look here, since it seems like Cloudflare conflicts with otherwise how we suggest that environment variables work.

[florian-lefebvre]

Yeah I think we need to provide some clarifications because it's a common source of support threads and issues:

1. In dev/build, we use loadEnv() from vite, which AFAIK loads things from .env, .env.${mode} and process.env
2. In production, secrets are not loaded by default because it depends a lot on the host. Eg. vercel/netlify/cloudflare inject env but while self-hosting, the user needs to load env themselves (inline cli args, dotenv whatever)
3. Cloudflare is always different:
   a. In dev/build, it uses loadEnv() and loads env through the platform proxy, so .dev.vars, from the wrangler config etc
   b. In prod, secrets are only available within the request scope (already documented as a limitation)
   c. All env can also be used from context.locals.runtime.env. It has the advantage of being more explicit in the sense that context is only available in the request scope. It also contains non env stuff, such as bindings

Hope that helps, I don't know where all this info should live but I think we need to provide more info, especially n°2

[sarah11918]

Yeah, this all sounds like helpful context. Do our three adapters (Node, Vercel, Netlify) all work the same (or mostly the same), and of our official adapters, Cloudflare is the only different one? In that case, it might be worth a specific Cloudflare section that could either be on this page, or a mention as a link to the Cloudflare adapter docs. If they're all a little different, then maybe a section for each one is needed, either on the Environment variable page or on each adapter page.

Because this is a common source of confusion/issues, I'll put help wanted on this and we are happy to have people work on this!

[florian-lefebvre]

I'd say:

• Vercel/Netlify work with no config
• Cloudflare is different (as always) but works with no config
• Node needs loading env manually

[9thQuadrant]

@sarah11918 i would like to work on this.
Although I understand the context here that env variable are handled differently in cloudflare, Could you please provide me with some more context on this so that I can get some broader idea

[florian-lefebvre]

FYI withastro/astro#13444 will probably make some of the info I shared here before outdated