Document the process.env handling and compat flags

Refs: cloudflare/workerd#3311

Author: jasnell

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

@@ -0,0 +1,22 @@
+---
+_build:
+  publishResources: false
+  render: never
+  list: never
+
+name: "Populate process.env from environment variables"
+sort_date: "2025-04-01"
+enable_flag: "nodejs_compat_populate_process_env"
+enable_date: "2025-04-01"
+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 as string values to the `process.env` global.
+
+If the `disallow_importable_env` compatibility flag is set, the `process.env`
+will not be populated.
+
+Refer to the [environment variables](/workers/configuration/environment-variables/) documentation
+for more detail.

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

@@ -97,6 +97,48 @@ Select the **Secret** type if your environment variable is a [secret](/workers/c
 
 <Render file="secrets-in-dev" />
 
+## Environment variables and Node.js compatibility
+
+When you enable both the [`nodejs_compat`](/workers/runtime-apis/nodejs/) and
+[`nodejs_compat_populate_process_env`](/workers/configuration/compatibility-flags/)
+compatibility flags, and the `disallow_importable_env` compatibility flag is
+not set, environment variables will also be available via the global
+`process.env`. Note that the `nodejs_compat_populate_process_env` flag is
+enabled automatically when `nodejs_compat` is used with a compatibility date
+on or after April 1st, 2025.
+
+The `process.env` will be populated lazily the first time that `process` is accessed
+in the worker.
+
+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, two text values, and
+one JSON value:
+
+```
+[vars]
+FOO =  "abc"
+BAR =  "abc"
+BAZ = { "a": 123 }
+```
+
+Environment variables can be added using either the `wrangler.{json|jsonc|toml}` file or via the Cloudflare
+dashboard UI.
+
+The values of `process.env.FOO` and `process.env.BAR` will each be the
+JavaScript string `"abc"`.
+
+The value of `process.env.BAZ` will be the JSON-encoded string `"{ \"a\": 123 }"`.
+
+:::note
+Note also that because secrets are a form of environment variable within the runtime,
+secrets are also exposed via `process.env`.
+
 ## Related resources
 
 - Migrating environment variables from [Service Worker format to ES modules syntax](/workers/reference/migrate-to-module-workers/#environment-variables).

src/content/docs/workers/configuration/secrets.mdx

@@ -9,7 +9,8 @@ import { Render } from "~/components";
 
 ## Background
 
-Secrets are a type of binding that allow you to attach encrypted text values to your Worker. You cannot see secrets after you set them and can only access secrets via [Wrangler](/workers/wrangler/commands/#secret) or programmatically via the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters). Secrets are used for storing sensitive information like API keys and auth tokens. Secrets are available on the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters) passed to your Worker's [`fetch` event handler](/workers/runtime-apis/handlers/fetch/).
+Secrets are a type of binding that allow you to attach encrypted text values to your Worker. You cannot see secrets after you set them and can only access secrets via [Wrangler](/workers/wrangler/commands/#secret) or programmatically via the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters). Secrets are used for storing sensitive information like API keys and auth tokens. Secrets are available on the [`env` parameter](/workers/runtime-apis/handlers/fetch/#parameters) passed to your Worker's [`fetch` event handler](/workers/runtime-apis/handlers/fetch/),
+and may also be accessible via `process.env` in Workers that support Node.js compatibility.
 
 ## Access your secrets with Workers
 
@@ -111,4 +112,4 @@ To delete a secret from your Worker project via the dashboard:
 ## Related resources
 
 - [Wrangler secret commands](/workers/wrangler/commands/#secret) - Review the Wrangler commands to create, delete and list secrets.
-- [Cloudflare Secrets Store](/secrets-store/) - Encrypt and store sensitive information as secrets that are securely reusable across your account.
+- [Cloudflare Secrets Store](/secrets-store/) - Encrypt and store sensitive information as secrets that are securely reusable across your account.

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

@@ -33,7 +33,16 @@ When [Node.js compatibility](/workers/runtime-apis/nodejs/) is turned on and the
 
 ### 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 via the `process.env` API. It is
+To automatically populate environment variables and secrets on `process.env`, enable
+the `nodejs_compat_populate_process_env` compatibility flag and disable the
+`disallow_importable_env` compatibility flag. It is also possible to
+manually copy these values into `process.env` if necessary -- but only within the context of
+a request.
+
+Setting any value on `process.env` will coerce that value into a string.
 
 ```js
 import * as process from 'node:process';
@@ -51,7 +60,11 @@ 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.
+It is strongly recommended that you *do not* replace the entire `process.env` object with
+the cloudflare `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';
@@ -63,7 +76,6 @@ 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!
-```
 
 ## `process.nextTick()`