Add fine-grained environment variable injection control

[Copilot]

Astro's Netlify adapter disables all environment variables by default, which prevents platform vars (NETLIFY_LOCAL, CONTEXT, SITE_ID) from being available in local dev. This breaks platform features like purgeCache() that require these vars.

Changes

• Added environmentVariables.injectUserEnv option (default: true)

  • When false: injects only platform env vars from 'general' and 'internal' sources
  • When true: injects all env vars including user-defined ones from account, UI, config files, and addons

• Updated injectEnvVariables() function

  • Added isPlatformEnvironmentVariable() helper to identify platform vars by source
  • Filters out user-defined vars when injectUserEnv is false

• Tests and documentation

  • Added tests in both @netlify/dev and @netlify/vite-plugin packages
  • Updated README files with usage examples

Usage

For integrations that manage their own env vars but need platform functionality:

netlify({
  environmentVariables: {
    enabled: true,
    injectUserEnv: false  // Only inject NETLIFY_LOCAL, CONTEXT, SITE_ID, etc.
  }
})

This allows Astro's adapter to enable platform vars without surprising users with injected env vars from their Netlify site.

Original prompt

Issue Title: Add fine-grained env var injection to Vite plugin and Astro adapter
Issue Description: Astro’s Netlify adapter disables the Vite plugin’s environment variables feature by default, which prevents basic platform vars (e.g., NETLIFY_LOCAL, CONTEXT, SITE_ID) from being available in local dev. This led to differences vs. netlify dev (e.g., purgeCache() failing without a site ID when using the Vite plugin).

Proposal:

• Add a more granular option to the Vite plugin, e.g. features.environmentVariables.injectUserEnv: boolean, so platform env vars can be enabled without injecting user-defined env.
• Update the Astro Netlify adapter to use this option so platform vars are available by default while user env remains off if desired.

References:

• Astro adapter disables env vars by default: https://github.com/withastro/astro/blob/54803d7e4f16029810b43694b37e2e6a25b5ce59/packages/integrations/netlify/src/index.ts#L618-L624
• Background discussion noting purgeCache() behavior and env var defaults: thread context
• Related defaults in @netlify/config: https://github.com/netlify/build/blob/3bf580227e8efae895429a3c3871fcd6f7185a74/packages/config/src/env/main.ts#L111
  Fixes https://linear.app/netlify/issue/FRB-2020/add-fine-grained-env-var-injection-to-vite-plugin-and-astro-adapter

Comment by User db2967f5-c49c-428b-ae14-6c61855027c1:
netlify/primitives

Comment by User c8ba5c18-8b2b-41c2-8484-9ca4ad793475:
📋 I wasn't able to determine which GitHub repository to work in.

I think it's one of these, but can you tell me which one is right?

Comment by User c8ba5c18-8b2b-41c2-8484-9ca4ad793475:
📋 I wasn't able to determine which GitHub repository to work in.

I think it's one of these, but can you tell me which one is right?

Comment by User :
This thread is for an agent session with githubcopilot.

Comment by User :
This thread is for an agent session with githubcopilot.

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
Seems like they preferred to release after ensuring the prompt is good, rather than releasing garbage quickly 😉

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
Nice!

Comment by User db2967f5-c49c-428b-ae14-6c61855027c1:
Wow I'm impressed. That Linear issue description is perfect.

Comment by User :
Created issue FRB-2020

Comment by User db2967f5-c49c-428b-ae14-6c61855027c1:
This comment thread is synced to a corresponding thread in Slack. All replies are displayed in both locations.

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
Meanwhile, merged updates https://github.com/netlify-templates/astro-platform-starter

Comment by User db2967f5-c49c-428b-ae14-6c61855027c1:
let me try this new fancy thing...
@linear create an issue to add the more fine-grained env var option I mentioned above to the vite plugin + update the astro netlify adapter to use it

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
But seems like the scope of not enabling it is a bit wider than we thought, or we'd have taken care of the "platform" env vars then

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
Yeah, I recall that we talked to @matthew Phillips about that

Comment by User db2967f5-c49c-428b-ae14-6c61855027c1:
trying to remember what astro was even trying to solve by disable env vars... found the PR that did it: withastro/astro#14078. :confused-travolta:

Seems like it was just about the surprise factor / potentially breaking change:

First, the Vite plugin was injecting env vars from linked Netlify sites. This is nice DX, but is a change that could surprise peopel - suddenly their dev environment had variables they weren't expecting, which could mess with their local setup.

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
anyway this solves the purgeCache() failure, but I was curious if I would get AI Gateway env vars as well, and the answer's still no 😕

Comment by User 8e14cbd8-ca68-4b55-956a-3ba8677986e0:
I agree, we should bring that up since our own platform functionality is impaired

Comment by User db2967f5-c49c-428b-ae14-6c61855027c1:
btw arguably the @astrojs/netlify docs are lying here (they say the env vars feature is enabled, then lower on the page it says disabled): [https://docs.astro.build/en/guides/integrations-guide/netlify/#local-development-features](https://docs.astro.build/en/guides/integrations-guide/netlify/#local-development...

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.