diff --git a/src/content/changelog/workers/2025-03-11-process-env-support.mdx b/src/content/changelog/workers/2025-03-11-process-env-support.mdx new file mode 100644 index 000000000000000..0ffd649ba2896ee --- /dev/null +++ b/src/content/changelog/workers/2025-03-11-process-env-support.mdx @@ -0,0 +1,32 @@ +--- +title: Access your Worker's environment variables from process.env +description: With Node.js compatability on, process.env is automatically populated with environment variables and secrets +products: + - workers +date: 2025-03-11T15:00:00Z +--- + +You can now access [environment variables](/workers/configuration/environment-variables/) and +[secrets](/workers/configuration/secrets/) on [`process.env`](/workers/runtime-apis/nodejs/process/#processenv) +when using the [`nodejs_compat` compatability flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). + +```js +const apiClient = ApiClient.new({ apiKey: process.env.API_KEY }); +const LOG_LEVEL = process.env.LOG_LEVEL || "info"; +``` + +In Node.js, environment variables are exposed via the global `process.env` object. Some libraries +assume that this object will be populated, and many developers may be used to accessing variables +in this way. + +Previously, the `process.env` object was always empty unless written to in Worker code. This could +cause unexpected errors or friction when developing Workers using code previously written for Node.js. + +Now, [environment variables](/workers/configuration/environment-variables/), +[secrets](/workers/configuration/secrets/), and [version metadata](/workers/runtime-apis/bindings/version-metadata/) +can all be accessed on `process.env`. + +After April 1, 2025, populating `process.env` will become the default behavior when `nodejs_compat` is enabled, and +your Worker's compatability date is after "2025-04-01". Until then, users can opt-in to this behavior by adding the +[`nodejs_compat_populate_process_env`](/workers/configuration/compatibility-flags/#enable-auto-populating-processenv) +compatability flag. diff --git a/src/content/compatibility-flags/nodejs-compat-populate-process-env.md b/src/content/compatibility-flags/nodejs-compat-populate-process-env.md new file mode 100644 index 000000000000000..e2be83bfacf1797 --- /dev/null +++ b/src/content/compatibility-flags/nodejs-compat-populate-process-env.md @@ -0,0 +1,25 @@ +--- +name: "Enable auto-populating `process.env`" +sort_date: "2025-02-27" +enable_date: "2025-04-01" +enable_flag: "nodejs_compat_populate_process_env" +disable_flag: "nodejs_compat_do_not_populate_process_env" +--- + +When you enable the `nodejs_compat_populate_process_env` compatibility flag and the [`nodejs_compat`](/workers/runtime-apis/nodejs/) +flag is also enabled, `process.env` will be populated with values from any bindings with text or JSON values. +This means that if you have added [environment variables](/workers/configuration/environment-variables/), +[secrets](/workers/configuration/secrets/), or [version metadata](/workers/runtime-apis/bindings/version-metadata/) +bindings, these values can be accessed on `process.env`. + +```js +const apiClient = ApiClient.new({ apiKey: process.env.API_KEY }); +const LOG_LEVEL = process.env.LOG_LEVEL || "info"; +``` + +This makes accessing these values easier and conforms to common Node.js patterns, which can +reduce toil and help with compatability for existing Node.js libraries. + +If users do not wish for these values to be accessible via `process.env`, they can use the +`nodejs_compat_do_not_populate_process_env` flag. In this case, `process.env` will still be +available, but will not have values automatically added. diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index 651e74149d2acc2..07d70647bf10d00 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -26,7 +26,10 @@ nextTick(() => { ## `process.env` -In the Node.js implementation of `process.env`, the `env` object is a copy of the environment variables at the time the process was started. In the Workers implementation, there is no process-level environment, so `env` is an empty object. You can still set and get values from `env`, and those will be globally persistent for all Workers running in the same isolate and context (for example, the same Workers entry point). +In the Node.js implementation of `process.env`, the `env` object is a copy of the environment variables at the time the process was started. In the Workers implementation, there is no process-level environment, so by default `env` is an empty object. You can still set and get values from `env`, and those will be globally persistent for all Workers running in the same isolate and context (for example, the same Workers entry point). + +When [Node.js compatability](/workers/runtime-apis/nodejs/) is turned on and the [`nodejs_compat_populate_process_env`](/workers/configuration/compatibility-flags/#enable-auto-populating-processenv) compatability flag is set, `process.env` will contain any [environment variables](/workers/configuration/environment-variables/), +[secrets](/workers/configuration/secrets/), or [version metadata](/workers/runtime-apis/bindings/version-metadata/) metadata that has been configured on your Worker. ### Relationship to per-request `env` argument in `fetch()` handlers