Netlify Build Plugins ↔ Deploy Previews: Environment Variable Propagation

Variable Propagation and Runtime Availability

Environment variables modified or set by Netlify Build Plugins during the build process do not propagate to the runtime environment of a Deploy Preview. Because Build Plugins execute as part of the CI/CD pipeline, any changes they make to the process environment are ephemeral and limited to the build container. They are not persisted back to the Netlify UI or injected into the serverless functions/runtime of the resulting deployment.

Build-Time vs. Runtime Scope

To understand why this happens, it is necessary to distinguish between the build phase and the runtime phase:

• Build Phase: Plugins have access to variables defined in the Netlify UI (scoped to "Builds" or "All") and netlify.toml. While a plugin can modify process.env within its own Node.js execution, these changes do not persist once the build container is destroyed.
• Runtime Phase: Deploy Previews inherit variables defined in the Netlify UI (scoped to "Functions" or "All"). Since the plugin's modifications were never written to the project's permanent configuration, the runtime environment remains unaware of them.

Behavior in Deploy Previews

When a Deploy Preview is triggered, the following logic applies to variable precedence and caching:

1. Precedence: If a plugin attempts to set a variable that is already defined in the Netlify UI, the UI setting typically takes precedence for the overall build environment, though the plugin may temporarily override it in memory during its own execution.
2. Caching: Enabling a plugin's cache key allows the plugin to persist files (artifacts) between builds. However, cache keys do not persist environment variables. If a plugin calculates a value and saves it to a file in the cache, that file can be read in subsequent builds, but the variable will not automatically appear in the environment.

Verification Steps

To verify which variables are actually available during your Deploy Preview build, add a temporary debug step to your build plugin:

console.log("Current Build Environment:", JSON.stringify(process.env, null, 2));

Compare the output in the Deploy Preview build logs against the Production build logs. Any variable missing from the Preview logs is likely scoped exclusively to "Production" in your Netlify site settings.

Diagnostic Requirement

To provide a more specific workaround, please clarify: Are you attempting to pass these variables to a frontend framework (e.g., via .env files) or to Netlify Functions at runtime?