From b3ebcc46b14083740b290b090ff877a320bee787 Mon Sep 17 00:00:00 2001 From: Mike Nomitch Date: Fri, 7 Mar 2025 14:49:50 -0800 Subject: [PATCH 1/5] Adds changelog and flag information for process.env population --- .../2025-03-07-process-env-support.mdx | 33 +++++++++++++++++++ .../nodejs-compat-populate-process-env.md | 27 +++++++++++++++ 2 files changed, 60 insertions(+) create mode 100644 src/content/changelog/workers/2025-03-07-process-env-support.mdx create mode 100644 src/content/compatibility-flags/nodejs-compat-populate-process-env.md diff --git a/src/content/changelog/workers/2025-03-07-process-env-support.mdx b/src/content/changelog/workers/2025-03-07-process-env-support.mdx new file mode 100644 index 000000000000000..fb59f91dd83a401 --- /dev/null +++ b/src/content/changelog/workers/2025-03-07-process-env-support.mdx @@ -0,0 +1,33 @@ +--- +title: Access environment variables on process.env in you Worker +description: With Node.js compatability on, process.env is automatically populated with environment variables and secrets +products: + - workers +date: 2025-03-07T11: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 variable 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 added when Node.js compatability was turned on, but it was empty. +This could cause unexpected errors or friction when developing Workers with 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/#nodejs-compat-populate-process-env) +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..744f67efa7f2042 --- /dev/null +++ b/src/content/compatibility-flags/nodejs-compat-populate-process-env.md @@ -0,0 +1,27 @@ +--- +name: "Enable `cache: no-store` HTTP standard API" +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 [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 `proecess.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`. In this case, `process.env` will still be available, +but will not have values automatically added. + +This flag will default to on for any compatability dates after `2025-04-01`. From c2528f7ebffe69fc2871d588a0ea055a5416b1ec Mon Sep 17 00:00:00 2001 From: Mike Nomitch Date: Fri, 7 Mar 2025 15:41:39 -0800 Subject: [PATCH 2/5] Updates title of compat flag --- .../changelog/workers/2025-03-07-process-env-support.mdx | 2 +- .../compatibility-flags/nodejs-compat-populate-process-env.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/changelog/workers/2025-03-07-process-env-support.mdx b/src/content/changelog/workers/2025-03-07-process-env-support.mdx index fb59f91dd83a401..ad9e0cd974dc7c2 100644 --- a/src/content/changelog/workers/2025-03-07-process-env-support.mdx +++ b/src/content/changelog/workers/2025-03-07-process-env-support.mdx @@ -3,7 +3,7 @@ title: Access environment variables on process.env in you Worker description: With Node.js compatability on, process.env is automatically populated with environment variables and secrets products: - workers -date: 2025-03-07T11:00:00Z +date: 2025-03-07T15:00:00Z --- You can now access [environment variables](/workers/configuration/environment-variables/) and diff --git a/src/content/compatibility-flags/nodejs-compat-populate-process-env.md b/src/content/compatibility-flags/nodejs-compat-populate-process-env.md index 744f67efa7f2042..13ec9868ccc3e25 100644 --- a/src/content/compatibility-flags/nodejs-compat-populate-process-env.md +++ b/src/content/compatibility-flags/nodejs-compat-populate-process-env.md @@ -1,5 +1,5 @@ --- -name: "Enable `cache: no-store` HTTP standard API" +name: "Enable auto-populating `process.env`" sort_date: "2025-02-27" enable_date: "2025-04-01" enable_flag: "nodejs_compat_populate_process_env" From 5d5fd077851a5b25422218fc2819b87f3603289f Mon Sep 17 00:00:00 2001 From: Mike Nomitch Date: Mon, 10 Mar 2025 22:16:23 -0700 Subject: [PATCH 3/5] Wording tweaks and added to main process env docs --- .../workers/2025-03-07-process-env-support.mdx | 11 +++++------ .../nodejs-compat-populate-process-env.md | 10 ++++------ .../docs/workers/runtime-apis/nodejs/process.mdx | 5 ++++- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/src/content/changelog/workers/2025-03-07-process-env-support.mdx b/src/content/changelog/workers/2025-03-07-process-env-support.mdx index ad9e0cd974dc7c2..6941f388f4f2550 100644 --- a/src/content/changelog/workers/2025-03-07-process-env-support.mdx +++ b/src/content/changelog/workers/2025-03-07-process-env-support.mdx @@ -1,5 +1,5 @@ --- -title: Access environment variables on process.env in you Worker +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 @@ -15,13 +15,12 @@ const apiClient = ApiClient.new({ apiKey: process.env.API_KEY }); const LOG_LEVEL = process.env.LOG_LEVEL || "info"; ``` -In Node.js, environment variable are exposed via the global `process.env` object. Some libraries +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 added when Node.js compatability was turned on, but it was empty. -This could cause unexpected errors or friction when developing Workers with code previously written for -Node.js. +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/) @@ -29,5 +28,5 @@ 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/#nodejs-compat-populate-process-env) +[`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 index 13ec9868ccc3e25..e2be83bfacf1797 100644 --- a/src/content/compatibility-flags/nodejs-compat-populate-process-env.md +++ b/src/content/compatibility-flags/nodejs-compat-populate-process-env.md @@ -8,9 +8,9 @@ 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 [environment variables](/workers/configuration/environment-variables/), +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 `proecess.env`. +bindings, these values can be accessed on `process.env`. ```js const apiClient = ApiClient.new({ apiKey: process.env.API_KEY }); @@ -21,7 +21,5 @@ This makes accessing these values easier and conforms to common Node.js patterns 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`. In this case, `process.env` will still be available, -but will not have values automatically added. - -This flag will default to on for any compatability dates after `2025-04-01`. +`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..6192eaa2405670e 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/#nodejs-compat-populate-process-env) 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 From 2562375c3272cb9591f237320114b49ab90dbb1c Mon Sep 17 00:00:00 2001 From: Mike Nomitch Date: Mon, 10 Mar 2025 22:17:53 -0700 Subject: [PATCH 4/5] Fixing changelog time --- ...ocess-env-support.mdx => 2025-03-11-process-env-support.mdx} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename src/content/changelog/workers/{2025-03-07-process-env-support.mdx => 2025-03-11-process-env-support.mdx} (98%) diff --git a/src/content/changelog/workers/2025-03-07-process-env-support.mdx b/src/content/changelog/workers/2025-03-11-process-env-support.mdx similarity index 98% rename from src/content/changelog/workers/2025-03-07-process-env-support.mdx rename to src/content/changelog/workers/2025-03-11-process-env-support.mdx index 6941f388f4f2550..4f37a32ec65abd9 100644 --- a/src/content/changelog/workers/2025-03-07-process-env-support.mdx +++ b/src/content/changelog/workers/2025-03-11-process-env-support.mdx @@ -3,7 +3,7 @@ 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-07T15:00:00Z +date: 2025-03-11T17:00:00Z --- You can now access [environment variables](/workers/configuration/environment-variables/) and From 0655d8fccf600827213243dae1da9a5aa0b429d6 Mon Sep 17 00:00:00 2001 From: Mike Nomitch Date: Tue, 11 Mar 2025 07:06:23 -0700 Subject: [PATCH 5/5] Updates link to process env docs --- .../changelog/workers/2025-03-11-process-env-support.mdx | 2 +- src/content/docs/workers/runtime-apis/nodejs/process.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 index 4f37a32ec65abd9..0ffd649ba2896ee 100644 --- a/src/content/changelog/workers/2025-03-11-process-env-support.mdx +++ b/src/content/changelog/workers/2025-03-11-process-env-support.mdx @@ -3,7 +3,7 @@ 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-11T17:00:00Z +date: 2025-03-11T15:00:00Z --- You can now access [environment variables](/workers/configuration/environment-variables/) and diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index 6192eaa2405670e..07d70647bf10d00 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -28,7 +28,7 @@ nextTick(() => { 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/#nodejs-compat-populate-process-env) compatability flag is set, `process.env` will contain any [environment variables](/workers/configuration/environment-variables/), +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