Document the process.env handling and compat flags #19187

jasnell · 2025-01-14T01:11:40Z

Refs: cloudflare/workerd#3311

Summary

Screenshots (optional)

Documentation checklist

The documentation style guide has been adhered to.
If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
Files which have changed name or location have been allocated redirects.

Refs: cloudflare/workerd#3311

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

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

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

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

vicb

I added inline comments.

It would be great to add details to https://developers.cloudflare.com/workers/configuration/secrets/ -> mention the flag and process.env

Thanks

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

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

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

Co-authored-by: Victor Berchet <[email protected]>

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

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

vicb · 2025-02-26T07:34:46Z

I think the doc should mention when this flag will be active by default with nodejs_compat - 2025-04-01 it seems

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

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

vicb · 2025-03-01T08:45:28Z

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

@@ -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


Maybe expland "the cloudflare env object + passed the fetch handler, imported from cloudflare:workers or retrieved from an entry point"

Suggested change

the request `env` object. Doing so will cause you to lose any environment variables that

the cloudflare `env` object. Doing so will cause you to lose any environment variables that

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

Co-authored-by: Victor Berchet <[email protected]>

hyperlint-ai · 2025-04-24T17:20:16Z

Howdy and thanks for contributing to our repo. The Cloudflare team reviews new, external PRs within two (2) weeks. If it's been two weeks or longer without any movement, please tag the PR Assignees in a comment.

We review internal PRs within 1 week. If it's something urgent or has been sitting without a comment, start a thread in the Developer Docs space internally.

PR Change Summary

Documented the handling of process.env and compatibility flags for Node.js in the Workers documentation.

Added a new section on populating process.env from environment variables using compatibility flags.
Updated the environment variables documentation to clarify how Node.js compatibility flags affect variable accessibility.
Enhanced the Node.js process documentation to explain the relationship between environment variables and process.env.

Modified Files

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

Added Files

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

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

Co-authored-by: Brendan Irvine-Broque <[email protected]>

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

Co-authored-by: Victor Berchet <[email protected]>

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

vicb · 2025-04-29T12:23:59Z

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

+  list: never
+
+name: "Populate process.env from environment variables"
+sort_date: "2025-01-31"


sort_date is usually the same as enable_date
Is there any reason to have a difference here?

Suggested change

sort_date: "2025-01-31"

sort_date: "2025-04-01"

vicb · 2025-04-29T12:25:27Z

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

+disable_flag: "nodejs_compat_do_not_populate_process_env"
+---
+
+When the `nodejs_compat_populate_process_env` compatibility flag is used in conjunction with


My understanding is that this also depends on disallow_importable_env in the latest impl.

ref: cloudflare/workerd#3778

vicb · 2025-04-29T12:26:19Z

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


Same comment as previously

vicb · 2025-04-29T12:26:56Z

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

+
+Text variable values are exposed directly.
+
+JSON variable values that evaluate to string values are exposed as the parsed value.


I remember that there were changes wrt .toJson(), does the description here need to be updated.

vicb · 2025-04-29T12:27:48Z

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

+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 }"`.


Suggested change

The value of `process.env.BAZ` will be the JSON-encoded string `"{ "a": 123 }"`.

The value of `process.env.BAZ` will be the JSON-encoded string `"{ \"a\": 123 }"`.

vicb · 2025-04-29T12:28:44Z

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

-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


Suggested change

By default, these are not accessible automatically via the `process.env` API. It is

By default, these are not accessible via the `process.env` API. It is

vicb · 2025-04-29T12:29:29Z

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

+
+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


again, does this depend on the disallow_importable_env flag?

Co-authored-by: Brendan Irvine-Broque <[email protected]>

vicb

It would be nice to:

handle all of the comments - meaning they don't have to be accepted but at least resolved
describe the interactions with disallow_importable_env

I would love to see some documentation for disallow_importable_env it might be in the current PR as they are closely related. If not it would be nice to have a tracking issue and make sure this gets documented.

Thanks!

Document the process.env handling and compat flags

23a80ff

Refs: cloudflare/workerd#3311

jasnell requested review from irvinebroque, mikenomitch, GregBrimble, a team, ToriLindsay and WalshyDev as code owners January 14, 2025 01:11

github-actions bot added size/s product:workers Related to Workers product labels Jan 14, 2025

github-actions bot assigned GregBrimble, irvinebroque, mikenomitch, ToriLindsay and WalshyDev Jan 14, 2025

This comment was marked as outdated.

Sign in to view

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

5c71b9d

Co-authored-by: hyperlint-ai[bot] <154288675+hyperlint-ai[bot]@users.noreply.github.com>

vicb reviewed Jan 14, 2025

View reviewed changes

src/content/compatibility-flags/process-env.md Outdated Show resolved Hide resolved

vicb reviewed Jan 14, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

vicb reviewed Jan 14, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Show resolved Hide resolved

vicb reviewed Jan 14, 2025

View reviewed changes

src/content/docs/workers/runtime-apis/nodejs/process.mdx Outdated Show resolved Hide resolved

vicb reviewed Jan 14, 2025

View reviewed changes

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

vicb reviewed Jan 14, 2025

View reviewed changes

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

vicb requested changes Jan 14, 2025

View reviewed changes

jasnell commented Feb 25, 2025

View reviewed changes

src/content/compatibility-flags/process-env.md Outdated Show resolved Hide resolved

jasnell commented Feb 25, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

jasnell commented Feb 25, 2025

View reviewed changes

src/content/docs/workers/runtime-apis/nodejs/process.mdx Outdated Show resolved Hide resolved

jasnell commented Feb 25, 2025

View reviewed changes

src/content/docs/workers/runtime-apis/nodejs/process.mdx Outdated Show resolved Hide resolved

Apply suggestions from code review

90b0399

Co-authored-by: Victor Berchet <[email protected]>

vicb reviewed Feb 26, 2025

View reviewed changes

src/content/compatibility-flags/process-env.md Outdated Show resolved Hide resolved

vicb reviewed Feb 26, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

vicb reviewed Feb 26, 2025

View reviewed changes

src/content/compatibility-flags/process-env.md Show resolved Hide resolved

vicb reviewed Mar 1, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Show resolved Hide resolved

vicb reviewed Mar 1, 2025

View reviewed changes

jasnell commented Apr 24, 2025

View reviewed changes

src/content/compatibility-flags/process-env.md Show resolved Hide resolved

Apply suggestions from code review

41c5be8

Co-authored-by: Victor Berchet <[email protected]>

jasnell requested a review from a team as a code owner April 24, 2025 17:19

Apply suggestions from code review

91e155e

Co-authored-by: Brendan Irvine-Broque <[email protected]>

jasnell commented Apr 24, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

jasnell commented Apr 24, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

Apply suggestions from code review

6e03e4c

Co-authored-by: Victor Berchet <[email protected]>

jasnell commented Apr 24, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

Apply suggestions from code review

91f4349

jasnell commented Apr 24, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

jasnell commented Apr 24, 2025

View reviewed changes

src/content/docs/workers/configuration/environment-variables.mdx Outdated Show resolved Hide resolved

Apply suggestions from code review

bdb2f73

jasnell requested review from vicb and irvinebroque April 24, 2025 17:30

vicb reviewed Apr 29, 2025

View reviewed changes

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

15bed00

Co-authored-by: Brendan Irvine-Broque <[email protected]>

vicb requested changes Apr 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document the process.env handling and compat flags #19187

Document the process.env handling and compat flags #19187

jasnell commented Jan 14, 2025 •

edited

Loading

This comment was marked as outdated.

vicb left a comment

vicb commented Feb 26, 2025

vicb Mar 1, 2025

hyperlint-ai bot commented Apr 24, 2025

vicb Apr 29, 2025

vicb Apr 29, 2025

vicb Apr 29, 2025

vicb Apr 29, 2025

vicb Apr 29, 2025

vicb Apr 29, 2025

vicb Apr 29, 2025

vicb left a comment

	the request `env` object. Doing so will cause you to lose any environment variables that
	the cloudflare `env` object. Doing so will cause you to lose any environment variables that


		Text variable values are exposed directly.

		JSON variable values that evaluate to string values are exposed as the parsed value.

	The value of `process.env.BAZ` will be the JSON-encoded string `"{ "a": 123 }"`.
	The value of `process.env.BAZ` will be the JSON-encoded string `"{ \"a\": 123 }"`.

	By default, these are not accessible automatically via the `process.env` API. It is
	By default, these are not accessible via the `process.env` API. It is

Document the process.env handling and compat flags #19187

Are you sure you want to change the base?

Document the process.env handling and compat flags #19187

Conversation

jasnell commented Jan 14, 2025 • edited Loading

Summary

Screenshots (optional)

Documentation checklist

This comment was marked as outdated.

vicb left a comment

Choose a reason for hiding this comment

vicb commented Feb 26, 2025

Choose a reason for hiding this comment

hyperlint-ai bot commented Apr 24, 2025

PR Change Summary

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vicb left a comment

Choose a reason for hiding this comment

jasnell commented Jan 14, 2025 •

edited

Loading