Document the process.env handling and compat flags

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

@@ -0,0 +1,19 @@
+---
+_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"
+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.
+
+Refer to the [environment variables](/workers/configuration/environment-variables/) documentation
+for more detail.

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

@@ -104,6 +104,47 @@ 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 you enable both the [`nodejs_compat`](/workers/runtime-apis/nodejs/) and
+[`nodejs_compat_populate_process_env`](/workers/configuration/compatibility-flags/)
+compatibility flags, 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
 
 * 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,15 @@ 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 and secrets 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 -- 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';
@@ -48,7 +56,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 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';
@@ -60,7 +72,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()`