feat: pass mutated config environment variables to functions during local development (#7325)

* feat: pass mutated config environment variables to functions during local development
## Summary

Fixes environment variables from build event handlers not being passed to functions during local development. Static config environment variables from `netlify.toml` were already working via global process environment injection, but variables added by plugins via build event handlers were not.

## Problem

Build event handlers (like `onPreDev`) could successfully mutate the config to add environment variables to `config.build.environment`, but these **mutated** environment variables were not available to functions in `process.env` during local development.

**What was working:**
- Static environment variables from `netlify.toml` → `cachedConfig.env` → global `process.env` → functions ✅
- Build event handler mutations → `config.build.environment` ✅  
- Process env override behavior ✅

**What was broken:**
- Mutated config environment variables → functions ❌

## Root Cause

Static config environment variables work because they're included in `cachedConfig.env` and injected into the global `process.env` via `injectEnvVariables()`. However, mutated config environment variables from build event handlers are only stored in `config.build.environment` and were never being passed to functions.

The `NetlifyFunction.invoke()` method was passing an empty `environment` object to the runtime, so functions only had access to the global `process.env` (which contained static config vars) but not the mutated config environment variables.

## Solution

Instead of injecting mutated config into the global `process.env` (which could affect other parts of the system), we:

- Extract environment variables from `config.build.environment` in `NetlifyFunction.invoke()`
- Pass them directly to the function runtime via the `environment` parameter  
- The runtime injects them into the function's specific `process.env`
- Maintain existing precedence: process env variables override config env variables

## Key Changes

### Core Implementation
- **`src/lib/functions/netlify-function.ts`**: Extract environment variables from mutated config and pass to runtime
- **`src/lib/functions/runtimes/js/index.ts`**: Update V1 function path to accept and use environment variables

### Testing
- **`tests/integration/commands/dev/functions.test.ts`**: Significantly expanded test coverage:
  - **NEW**: Static config environment variables for V1 functions
  - **NEW**: Build event handler environment variables for V1 functions  
  - **NEW**: Static config environment variables for V2 functions *(first V2 function env var tests)*
  - **NEW**: Build event handler environment variables for V2 functions *(first V2 function env var tests)*
  - **NEW**: Environment variable precedence for both V1 and V2 functions *(first build event handler mutation tests)*

**Note**: While static config environment variables were already tested in `dev.config.test.ts` for V1 functions, this PR adds the first comprehensive test coverage for V2 functions and build event handler mutations.

## Technical Details

This approach is better than global environment injection because:
- It doesn't pollute the global process environment
- It only affects the specific function being invoked  
- It maintains proper precedence handling
- It works for both V1 and V2 function runtimes

## Use Case

This enables plugins to add environment variables via build event handlers:

```javascript
// Plugin build event handler
export const onPreDev = ({ netlifyConfig }) => {
  netlifyConfig.build.environment.MY_PLUGIN_VAR = 'value'
}

// Function can now access the mutated config env var during local dev
export const handler = async (event, context) => {
  console.log(process.env.MY_PLUGIN_VAR) // 'value' ✅ (was undefined ❌)
  return { statusCode: 200, body: 'OK' }
}
```

## Test Coverage
✅ V1 Functions - Static config and build event handler environment variables
✅ V2 Functions - Static config and build event handler environment variables
✅ Environment variable precedence - Process env overrides config env for both function types
✅ Backwards compatibility - All existing functionality preserved (16 existing tests still pass)

Author: Caleb Barnes

src/lib/functions/netlify-function.ts

@@ -252,7 +252,23 @@ export default class NetlifyFunction<BuildResult extends BaseBuildResult> {
       throw new Error('Function timeout (`timeoutBackground` or `timeoutSynchronous`) not set')
     }
 
-    const environment = {}
+    // Get function environment variables from config.build.environment
+    // This allows build event handlers to add function-specific environment variables
+    // Only include config environment variables that are not already set in process.env
+    // to ensure process environment variables take precedence
+    const configEnvVars: Record<string, string> = {}
+    if (this.config.build?.environment) {
+      Object.entries(this.config.build.environment).forEach(([key, value]) => {
+        if (typeof value === 'string' && !(key in process.env)) {
+          configEnvVars[key] = value
+        }
+      })
+    }
+
+    const environment = {
+      // Include function-specific environment variables from config
+      ...configEnvVars,
+    }
 
     if (this.blobsContext) {
       const payload = JSON.stringify(getBlobsEventProperty(this.blobsContext))

src/lib/functions/runtimes/js/index.ts

@@ -69,7 +69,13 @@ export const invokeFunction = async ({
       ? buildData.runtimeAPIVersion
       : null
   if (runtimeAPIVersion == null || runtimeAPIVersion !== 2) {
-    return await invokeFunctionDirectly({ context, event, func, timeout })
+    return await invokeFunctionDirectly({
+      context,
+      environment: environment as Record<string, string>,
+      event,
+      func,
+      timeout,
+    })
   }
 
   const workerData = {
@@ -114,11 +120,13 @@ export const invokeFunction = async ({
 
 export const invokeFunctionDirectly = async <BuildResult extends JsBuildResult>({
   context,
+  environment,
   event,
   func,
   timeout,
 }: {
   context: Record<string, unknown>
+  environment: Record<string, string>
   event: Record<string, unknown>
   func: NetlifyFunction<BuildResult>
   timeout: number
@@ -134,6 +142,8 @@ export const invokeFunctionDirectly = async <BuildResult extends JsBuildResult>(
   const result = await lambdaLocal.execute({
     clientContext: JSON.stringify(context),
     environment: {
+      // Include environment variables from config
+      ...environment,
       // We've set the Blobs context on the parent process, which means it will
       // be available to the Lambda. This would be inconsistent with production
       // where only V2 functions get the context injected. To fix it, unset the

tests/integration/commands/dev/functions.test.ts

@@ -50,3 +50,216 @@ test('nodeModuleFormat: esm v1 functions should work', async (t) => {
     })
   })
 })
+
+test('should inject environment variables from config to functions', async (t) => {
+  await withSiteBuilder(t, async (builder) => {
+    await builder
+      .withNetlifyToml({
+        config: {
+          build: { environment: { MY_CONFIG_ENV: 'FROM_CONFIG' } },
+          functions: { directory: 'functions' },
+        },
+      })
+      .withFunction({
+        path: 'echo-config-env.js',
+        handler: () => {
+          return Promise.resolve({
+            statusCode: 200,
+            body: process.env.MY_CONFIG_ENV ?? 'NOT_FOUND',
+          })
+        },
+      })
+      .build()
+
+    await withDevServer({ cwd: builder.directory }, async (server) => {
+      const response = await fetch(new URL('/.netlify/functions/echo-config-env', server.url))
+      t.expect(await response.text()).toBe('FROM_CONFIG')
+      t.expect(response.status).toBe(200)
+    })
+  })
+})
+
+test('should inject environment variables from build event handlers to functions', async (t) => {
+  await withSiteBuilder(t, async (builder) => {
+    await builder
+      .withNetlifyToml({
+        config: {
+          build: { environment: { EXISTING_VAR: 'existing_value' } },
+          plugins: [{ package: './plugins/add-env-vars' }],
+          functions: { directory: 'functions' },
+        },
+      })
+      .withBuildPlugin({
+        name: 'add-env-vars',
+        plugin: {
+          onPreDev({ netlifyConfig }) {
+            // Simulate a build event handler adding environment variables to the config
+            // This is how plugins can add environment variables that should be available to functions
+            netlifyConfig.build.environment.MY_PLUGIN_ENV = 'FROM_BUILD_EVENT_HANDLER'
+          },
+        },
+      })
+      .withFunction({
+        path: 'echo-plugin-env.js',
+        handler: () => {
+          return Promise.resolve({
+            statusCode: 200,
+            body: JSON.stringify({
+              MY_PLUGIN_ENV: process.env.MY_PLUGIN_ENV ?? 'NOT_FOUND',
+              EXISTING_VAR: process.env.EXISTING_VAR ?? 'NOT_FOUND',
+            }),
+          })
+        },
+      })
+      .build()
+
+    await withDevServer({ cwd: builder.directory }, async (server) => {
+      const response = await fetch(new URL('/.netlify/functions/echo-plugin-env', server.url))
+      const result = (await response.json()) as { MY_PLUGIN_ENV: string; EXISTING_VAR: string }
+
+      // First verify that existing environment variables work
+      t.expect(result.EXISTING_VAR).toBe('existing_value')
+
+      // Then verify that build event handler environment variables work
+      t.expect(result.MY_PLUGIN_ENV).toBe('FROM_BUILD_EVENT_HANDLER')
+      t.expect(response.status).toBe(200)
+    })
+  })
+})
+
+test('should inject environment variables from config to V2 functions', async (t) => {
+  await withSiteBuilder(t, async (builder) => {
+    await builder
+      .withNetlifyToml({
+        config: {
+          build: { environment: { MY_CONFIG_ENV: 'FROM_CONFIG_V2' } },
+          functions: { directory: 'functions' },
+        },
+      })
+      .withFunction({
+        path: 'echo-config-env-v2.js',
+        runtimeAPIVersion: 2, // This makes it a V2 function
+        handler: () => {
+          return new Response(process.env.MY_CONFIG_ENV ?? 'NOT_FOUND', {
+            status: 200,
+          })
+        },
+      })
+      .build()
+
+    await withDevServer({ cwd: builder.directory }, async (server) => {
+      const response = await fetch(new URL('/.netlify/functions/echo-config-env-v2', server.url))
+      t.expect(await response.text()).toBe('FROM_CONFIG_V2')
+      t.expect(response.status).toBe(200)
+    })
+  })
+})
+
+test('should inject environment variables from build event handlers to V2 functions', async (t) => {
+  await withSiteBuilder(t, async (builder) => {
+    await builder
+      .withNetlifyToml({
+        config: {
+          build: { environment: { EXISTING_VAR: 'existing_value_v2' } },
+          plugins: [{ package: './plugins/add-env-vars-v2' }],
+          functions: { directory: 'functions' },
+        },
+      })
+      .withBuildPlugin({
+        name: 'add-env-vars-v2',
+        plugin: {
+          onPreDev({ netlifyConfig }) {
+            // Simulate a build event handler adding environment variables to the config
+            netlifyConfig.build.environment.MY_PLUGIN_ENV = 'FROM_BUILD_EVENT_HANDLER_V2'
+          },
+        },
+      })
+      .withFunction({
+        path: 'echo-plugin-env-v2.js',
+        runtimeAPIVersion: 2, // This makes it a V2 function
+        handler: () => {
+          return new Response(
+            JSON.stringify({
+              MY_PLUGIN_ENV: process.env.MY_PLUGIN_ENV ?? 'NOT_FOUND',
+              EXISTING_VAR: process.env.EXISTING_VAR ?? 'NOT_FOUND',
+            }),
+            {
+              status: 200,
+              headers: { 'Content-Type': 'application/json' },
+            },
+          )
+        },
+      })
+      .build()
+
+    await withDevServer({ cwd: builder.directory }, async (server) => {
+      const response = await fetch(new URL('/.netlify/functions/echo-plugin-env-v2', server.url))
+      const result = (await response.json()) as { MY_PLUGIN_ENV: string; EXISTING_VAR: string }
+
+      // First verify that existing environment variables work
+      t.expect(result.EXISTING_VAR).toBe('existing_value_v2')
+
+      // Then verify that build event handler environment variables work
+      t.expect(result.MY_PLUGIN_ENV).toBe('FROM_BUILD_EVENT_HANDLER_V2')
+      t.expect(response.status).toBe(200)
+    })
+  })
+})
+
+test('should respect environment variable precedence for both V1 and V2 functions', async (t) => {
+  await withSiteBuilder(t, async (builder) => {
+    await builder
+      .withNetlifyToml({
+        config: {
+          build: { environment: { TEST_PRECEDENCE: 'FROM_CONFIG' } },
+          plugins: [{ package: './plugins/precedence-test' }],
+          functions: { directory: 'functions' },
+        },
+      })
+      .withBuildPlugin({
+        name: 'precedence-test',
+        plugin: {
+          onPreDev({ netlifyConfig }) {
+            netlifyConfig.build.environment.TEST_PRECEDENCE = 'FROM_BUILD_EVENT_HANDLER'
+          },
+        },
+      })
+      .withFunction({
+        path: 'precedence-v1.js',
+        handler: () => {
+          return Promise.resolve({
+            statusCode: 200,
+            body: process.env.TEST_PRECEDENCE ?? 'NOT_FOUND',
+          })
+        },
+      })
+      .withFunction({
+        path: 'precedence-v2.js',
+        runtimeAPIVersion: 2,
+        handler: () => {
+          return new Response(process.env.TEST_PRECEDENCE ?? 'NOT_FOUND', {
+            status: 200,
+          })
+        },
+      })
+      .build()
+
+    await withDevServer(
+      {
+        cwd: builder.directory,
+        env: { TEST_PRECEDENCE: 'FROM_PROCESS_ENV' }, // Process env should override config
+      },
+      async (server) => {
+        // Test V1 function
+        const v1Response = await fetch(new URL('/.netlify/functions/precedence-v1', server.url))
+        t.expect(await v1Response.text()).toBe('FROM_PROCESS_ENV')
+        t.expect(v1Response.status).toBe(200)
+
+        // Test V2 function
+        const v2Response = await fetch(new URL('/.netlify/functions/precedence-v2', server.url))
+        t.expect(await v2Response.text()).toBe('FROM_PROCESS_ENV')
+        t.expect(v2Response.status).toBe(200)
+      },
+    )
+  })
+})