Document the process.env handling and compat flags

Refs: cloudflare/workerd#3311

Author: jasnell

src/content/compatibility-flags/process-env.md

@@ -0,0 +1,18 @@
+---
+_build:
+  publishResources: false
+  render: never
+  list: never
+
+name: "Populate process.env from environment variables"
+sort_date: "2025-01-31"
+enable_flag: "nodejs_compat_populate_process_env"
+disable_flag: "nodejs_compat_do_not_populate_process_env"
+---
+
+When the `nodejs_compat_populate_process_env` compatibility flag is used in conjunction with
+the `nodejs_compat` compatibility flag, all environment variables configured for the worker
+are added a string values to the `process.env` global.
+
+Refer to the [environment variables](/workers/configuration/environment-variables/) docuemntation
+for more detail.

src/content/docs/workers/configuration/environment-variables.mdx

@@ -104,6 +104,40 @@ Select the **Secret** type if your environment variable is a [secret](/workers/c
 
 <Render file="env_and_secrets" />
 
+## Environment variables and Node.js compatibility
+
+When using the `nodejs_compat` and `nodejs_compat_populate_process_env` compatibility
+flags, environment variables will also be available via the global `process.env`.
+
+Text variable values are exposed directly.
+
+JSON variable values that evaluate to string values are exposed as the parsed value.
+
+JSON variable values that do not evaluate to string values are exposed as the raw
+JSON string.
+
+For example, imagine a worker with three environment variables, one text value, and
+two JSON values:
+
+* `FOO` with plaintext value `abc`,
+* `BAR` with JSON value `"abc"`,
+* `BAZ` with JSON value `"{ "a": 123 }"`
+
+The value of `process.env.FOO` will be the JavaScript string `"abc"`.
+
+The value of `process.env.BAR` will be the JavaScript string `"abc"` (note that the
+JSON encoding is removed).
+
+The value of `process.env.BAZ` will be the JSON-encoded string `"{ "a": 123 }"`.
+
+These rules mean that if you have a JSON environment variable whose value is a
+JSON-encoded string and you *want* to be able to parse it as JSON within your
+application (e.g. `JSON.parse(process.env.BAR)`) then the value will need to
+be "double encoded", for instance `'"\\"abc\\""'`.
+
+Note also that because secrets are a form of environment variable within the runtime,
+secrets are also exposed via `process.env`.
+
 ## Related resources
 
 * Learn how to access environment variables in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

src/content/docs/workers/runtime-apis/nodejs/process.mdx

@@ -30,7 +30,14 @@ In the Node.js implementation of `process.env`, the `env` object is a copy of th
 
 ### Relationship to per-request `env` argument in `fetch()` handlers
 
-Workers do have a concept of [environment variables](/workers/configuration/environment-variables/) that are applied on a per-Worker and per-request basis. These are not accessible automatically via the `process.env` API. It is possible to manually copy these values into `process.env` if you need to. Be aware, however, that setting any value on `process.env` will coerce that value into a string.
+Workers have a concept of [environment variables](/workers/configuration/environment-variables/) that are applied on a per-Worker and per-request basis.
+
+By default, these are not accessible automatically via the `process.env` API. It is
+possible to have environment variables automatically populated into `process.env` using
+the `nodejs_compat_populate_process_env` compatibility flag. It is also possible to
+manually copy these values into `process.env` if necessary.
+
+Setting any value on `process.env` will coerce that value into a string.
 
 ```js
 import * as process from 'node:process';
@@ -48,19 +55,8 @@ export default {
 };
 ```
 
-It is strongly recommended that you *do not* replace the entire `process.env` object with the request `env` object. Doing so will cause you to lose any environment variables that were set previously and will cause unexpected behavior for other Workers running in the same isolate. Specifically, it would cause inconsistency with the `process.env` object when accessed via named imports.
-
-```js
-import * as process from 'node:process';
-import { env } from 'node:process';
-
-process.env === env; // true! they are the same object
-process.env = {}; // replace the object! Do not do this!
-process.env === env; // false! they are no longer the same object
-
-// From this point forward, any changes to process.env will not be reflected in env,
-// and vice versa!
-```
+Refer to the [environment variables](/workers/configuration/environment-variables/)
+documentation for more detail.
 
 ## `process.nextTick()`