From 734bea2fa3575f053e3727bafbd3043b891e6a17 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Sep 2025 13:10:15 -0700 Subject: [PATCH 1/7] document nodejs_process_v2 compat flag --- .../nodejs-compat-process-v2.md | 15 ++++ .../workers/runtime-apis/nodejs/index.mdx | 10 +-- .../workers/runtime-apis/nodejs/process.mdx | 77 ++++++++++++++++--- 3 files changed, 87 insertions(+), 15 deletions(-) create mode 100644 src/content/compatibility-flags/nodejs-compat-process-v2.md diff --git a/src/content/compatibility-flags/nodejs-compat-process-v2.md b/src/content/compatibility-flags/nodejs-compat-process-v2.md new file mode 100644 index 00000000000000..63574111339180 --- /dev/null +++ b/src/content/compatibility-flags/nodejs-compat-process-v2.md @@ -0,0 +1,15 @@ +--- +name: "Enable `process` v2 implementation" +sort_date: "2025-09-15" +enable_date: "2025-09-15" +enable_flag: "enable_nodejs_process_v2" +disable_flag: "disable_nodejs_process_v2" +--- + +When enabled, the `enable_nodejs_process_v2` flag along with the [`nodejs_compat`](/workers/runtime-apis/nodejs/) compat flag +ensures a comprehensive Node.js-compatible `process` implementation, updating from the previous minimal process implementation +that only provided the limited `nextTick`, `env`, `exit`, `getBuiltinModule`, `platform` and `features` properties. + +To continue using the previous minimal implementation after the compat date, set the `disable_nodejs_process_v2` flag instead. + +Most Node.js-supported process properties are implemented where possible, with undefined exports for unsupported features. See the Wo[process documentation](/workers/runtime-apis/nodejs/process/) for Workers-specific implementation details. diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index 7b6ed1d3454c58..1ac5bf00a242bf 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -47,20 +47,20 @@ The runtime APIs from Node.js listed below as "🟢 supported" are currently nat | Events | 🟢 supported | | File system | ⚪ coming soon | | Globals | 🟢 supported | -| HTTP | 🟢 supported | +| [HTTP](/workers/runtime-apis/nodejs/http/) | 🟢 supported | | HTTP/2 | ⚪ not yet supported | -| HTTPS | 🟢 supported | +| [HTTPS](/workers/runtime-apis/nodejs/https/) | 🟢 supported | | Inspector | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) | | [Net](/workers/runtime-apis/nodejs/net/) | 🟢 supported | | OS | ⚪ not yet supported | | [Path](/workers/runtime-apis/nodejs/path/) | 🟢 supported | | Performance hooks | 🟡 partially supported | -| Process | 🟢 supported | +| [Process](/workers/runtime-apis/nodejs/process/) | 🟢 supported | | Query strings | 🟢 supported | -| Stream | 🟢 supported | +| [Stream](/workers/runtime-apis/nodejs/streams/) | 🟢 supported | | [String decoder](/workers/runtime-apis/nodejs/string-decoder/) | 🟢 supported | | [Timers](/workers/runtime-apis/nodejs/timers/) | 🟢 supported | -| TLS/SSL | 🟡 partially supported | +| [TLS/SSL](/workers/runtime-apis/nodejs/tls/) | 🟡 partially supported | | UDP/datagram | ⚪ not yet supported | | [URL](/workers/runtime-apis/nodejs/url/) | 🟢 supported | | [Utilities](/workers/runtime-apis/nodejs/util/) | 🟢 supported | diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index 9ff3f411932255..4fa8eafc427f51 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -7,18 +7,14 @@ import { Render } from "~/components"; -The [`process`](https://nodejs.org/dist/latest-v19.x/docs/api/process.html) module in Node.js provides a number of useful APIs related to the current process. Within a serverless environment like Workers, most of these APIs are not relevant or meaningful, but some are useful for cross-runtime compatibility. Within Workers, the following APIs are available: +The [`process`](https://nodejs.org/dist/latest-v22.x/docs/api/process.html) module in Node.js provides a number of useful APIs related to the current process. -```js -import { env, nextTick } from "node:process"; +Initially Workers only supported `nextTick`, `env`, `exit`, `getBuiltinModule`, `platform` and `features` on process, +which was then updated with the [`enable_nodejs_process_v2`](/workers/configuration/compatibility-flags/#enable-process-v2-implementation) flag to include most Node.js process features. -env["FOO"] = "bar"; -console.log(env["FOO"]); // Prints: bar +Refer to the [Node.js documentation for `process`](https://nodejs.org/dist/latest-v22.x/docs/api/process.html) for more information. -nextTick(() => { - console.log("next tick"); -}); -``` +Workers-specific implementation details apply when adapting Node.js support for a serverless environment, which are described in more detail below. ## `process.env` @@ -77,5 +73,66 @@ process.env === env; // false! they are no longer the same object The Workers implementation of `process.nextTick()` is a wrapper for the standard Web Platform API [`queueMicrotask()`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/queueMicrotask). -Refer to the [Node.js documentation for `process`](https://nodejs.org/dist/latest-v19.x/docs/api/process.html) for more information. +```js +import { env, nextTick } from "node:process"; + +env["FOO"] = "bar"; +console.log(env["FOO"]); // Prints: bar + +nextTick(() => { + console.log("next tick"); +}); +``` + +## Stdio + +`process.stdout`, `process.stderr` and `process.stdin` are supported as streams. `stdin` is treated as an empty readable stream. +`stdout` and `stderr` are treated as non-TTY writable streams, with line buffering when integrating with inspector and structured +logging output. + +The line buffer is cleared by either a newline or the next microtask, so that synchronous writes without newline characters will always +remain contiguous on the same line. + +For example, the following will behave as if calling `console.log('one')` followed by `console.log('two')`: + +```js +// equivalent to `console.log('one');` +process.stdout.write('o'); +process.stdout.write('n'); +process.stdout.write('e'); +await 0; +// equivalent to `console.log('two')` +process.stdout.write('t'); +process.stdout.write('w'); +process.stdout.write('o'); +process.stdout.write('\n'); +// equivalent to `console.log('')` +process.stdout.write('\n'); +``` + +## Filesystem + +`process.cwd()` is initialized to `/bundle`. + +`process.chdir()` may be used to alter the current working directory, and is respected by FS operations when using `enable_nodejs_fs_module`. + +## Hrtime + +`process.hrtime` is now available, but currently provides an unaccurate timer for compatiblity only. + +## Unsupported Features + +The following process properties are currently entirely unsupported and return `undefined`: `binding`, `channel`, `connected`, `debugPort`, `dlopen`, +`exitCode`, `finalization`, `getActiveResourcesInfo`, `hasUncaughtExceptionCaptureCallback`, `kill`, `memoryUsage`, `noDeprecation`, `permission`, +`ref`, `release`, `report`, `resourceUsage`, `send`, `setUncaughtExceptionCaptureCallback`, `sourceMapsEnabled`, `threadCpuUsage`, +`throwDeprecation`, `traceDeprecation`, `unref`. + +These unimplemented features may be feature-detected via conditional gating patterns like: + +```js +if (process.dlopen) { + // use dlopen when available +} ``` + +Any of these remaining unimplemented features may be implemented in future. From 7d7694bdbee9c0e027915931d5a9fb7bed1c82f7 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Sep 2025 17:28:22 -0700 Subject: [PATCH 2/7] pr feedback --- .../nodejs-compat-process-v2.md | 2 +- .../workers/runtime-apis/nodejs/process.mdx | 21 ++++++++----------- 2 files changed, 10 insertions(+), 13 deletions(-) diff --git a/src/content/compatibility-flags/nodejs-compat-process-v2.md b/src/content/compatibility-flags/nodejs-compat-process-v2.md index 63574111339180..a1207e8ffb281e 100644 --- a/src/content/compatibility-flags/nodejs-compat-process-v2.md +++ b/src/content/compatibility-flags/nodejs-compat-process-v2.md @@ -6,7 +6,7 @@ enable_flag: "enable_nodejs_process_v2" disable_flag: "disable_nodejs_process_v2" --- -When enabled, the `enable_nodejs_process_v2` flag along with the [`nodejs_compat`](/workers/runtime-apis/nodejs/) compat flag +When enabled after 2025-09-15, the `enable_nodejs_process_v2` flag along with the [`nodejs_compat`](/workers/runtime-apis/nodejs/) compat flag ensures a comprehensive Node.js-compatible `process` implementation, updating from the previous minimal process implementation that only provided the limited `nextTick`, `env`, `exit`, `getBuiltinModule`, `platform` and `features` properties. diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index 4fa8eafc427f51..a7e2843c2bd43b 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -7,14 +7,14 @@ import { Render } from "~/components"; -The [`process`](https://nodejs.org/dist/latest-v22.x/docs/api/process.html) module in Node.js provides a number of useful APIs related to the current process. +The [`process`](https://nodejs.org/docs/latest/api/process.html) module in Node.js provides a number of useful APIs related to the current process. Initially Workers only supported `nextTick`, `env`, `exit`, `getBuiltinModule`, `platform` and `features` on process, which was then updated with the [`enable_nodejs_process_v2`](/workers/configuration/compatibility-flags/#enable-process-v2-implementation) flag to include most Node.js process features. -Refer to the [Node.js documentation for `process`](https://nodejs.org/dist/latest-v22.x/docs/api/process.html) for more information. +Refer to the [Node.js documentation for `process`](https://nodejs.org/docs/latest/api/process.html) for more information. -Workers-specific implementation details apply when adapting Node.js support for a serverless environment, which are described in more detail below. +Workers-specific implementation details apply when adapting Node.js process support for a serverless environment, which are described in more detail below. ## `process.env` @@ -86,14 +86,13 @@ nextTick(() => { ## Stdio -`process.stdout`, `process.stderr` and `process.stdin` are supported as streams. `stdin` is treated as an empty readable stream. +[`process.stdout`](https://nodejs.org/docs/latest/api/process.html#processstdout), [`process.stderr`](https://nodejs.org/docs/latest/api/process.html#processstderr) and [`process.stdin`](https://nodejs.org/docs/latest/api/process.html#processstdin) are supported as streams. `stdin` is treated as an empty readable stream. `stdout` and `stderr` are treated as non-TTY writable streams, with line buffering when integrating with inspector and structured logging output. -The line buffer is cleared by either a newline or the next microtask, so that synchronous writes without newline characters will always -remain contiguous on the same line. +The line buffer works by storing writes to stdout or stderr until either a newline character `\n` is encountered or until the next microtask, when the log is then flushed to the output. -For example, the following will behave as if calling `console.log('one')` followed by `console.log('two')`: +This way, synchronous writes without newline characters will always remain contiguous on the same line. For example, the following will behave as if calling `console.log('one')` followed by `console.log('two')`: ```js // equivalent to `console.log('one');` @@ -112,13 +111,13 @@ process.stdout.write('\n'); ## Filesystem -`process.cwd()` is initialized to `/bundle`. +[`process.cwd()`](https://nodejs.org/docs/latest/api/process.html#processcwd) is the _current workding directory_, used as the default path for all filesystem operations, and is initialized to `/bundle`. -`process.chdir()` may be used to alter the current working directory, and is respected by FS operations when using `enable_nodejs_fs_module`. +[`process.chdir()`](https://nodejs.org/docs/latest/api/process.html#processchdirdirectory) allows modifying the `cwd` and is respected by FS operations when using `enable_nodejs_fs_module`. ## Hrtime -`process.hrtime` is now available, but currently provides an unaccurate timer for compatiblity only. +While [`process.hrtime`](https://nodejs.org/docs/latest/api/process.html#processhrtimetime) high-resolution timer is available, it provides an inaccurate timer for compatibility only. ## Unsupported Features @@ -134,5 +133,3 @@ if (process.dlopen) { // use dlopen when available } ``` - -Any of these remaining unimplemented features may be implemented in future. From 445f9cf7ff929fcbdcbc7bafc9a07a32175a43ed Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Wed, 3 Sep 2025 17:29:12 -0700 Subject: [PATCH 3/7] remove logging example --- .../workers/runtime-apis/nodejs/process.mdx | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index a7e2843c2bd43b..3a6c48b15d6f8b 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -92,22 +92,7 @@ logging output. The line buffer works by storing writes to stdout or stderr until either a newline character `\n` is encountered or until the next microtask, when the log is then flushed to the output. -This way, synchronous writes without newline characters will always remain contiguous on the same line. For example, the following will behave as if calling `console.log('one')` followed by `console.log('two')`: - -```js -// equivalent to `console.log('one');` -process.stdout.write('o'); -process.stdout.write('n'); -process.stdout.write('e'); -await 0; -// equivalent to `console.log('two')` -process.stdout.write('t'); -process.stdout.write('w'); -process.stdout.write('o'); -process.stdout.write('\n'); -// equivalent to `console.log('')` -process.stdout.write('\n'); -``` +This ensures compatibility with inspector and structured logging outputs. ## Filesystem From d9a0c73a841e4e5a1560151879867e31a991e680 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Thu, 4 Sep 2025 09:45:06 +0200 Subject: [PATCH 4/7] Apply suggestion from @vicb --- src/content/compatibility-flags/nodejs-compat-process-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/compatibility-flags/nodejs-compat-process-v2.md b/src/content/compatibility-flags/nodejs-compat-process-v2.md index a1207e8ffb281e..8837310cf7e872 100644 --- a/src/content/compatibility-flags/nodejs-compat-process-v2.md +++ b/src/content/compatibility-flags/nodejs-compat-process-v2.md @@ -12,4 +12,4 @@ that only provided the limited `nextTick`, `env`, `exit`, `getBuiltinModule`, `p To continue using the previous minimal implementation after the compat date, set the `disable_nodejs_process_v2` flag instead. -Most Node.js-supported process properties are implemented where possible, with undefined exports for unsupported features. See the Wo[process documentation](/workers/runtime-apis/nodejs/process/) for Workers-specific implementation details. +Most Node.js-supported process properties are implemented where possible, with undefined exports for unsupported features. See the [process documentation](/workers/runtime-apis/nodejs/process/) for Workers-specific implementation details. From 9a4ab3fd54a73dcc892a208e8f93661676bcf439 Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Thu, 4 Sep 2025 09:48:59 +0200 Subject: [PATCH 5/7] Apply suggestion from @vicb --- src/content/docs/workers/runtime-apis/nodejs/process.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index 3a6c48b15d6f8b..830842e838475f 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -106,7 +106,7 @@ While [`process.hrtime`](https://nodejs.org/docs/latest/api/process.html#process ## Unsupported Features -The following process properties are currently entirely unsupported and return `undefined`: `binding`, `channel`, `connected`, `debugPort`, `dlopen`, +The following `process` properties are currently entirely unsupported and return `undefined`: `binding`, `channel`, `connected`, `debugPort`, `dlopen`, `exitCode`, `finalization`, `getActiveResourcesInfo`, `hasUncaughtExceptionCaptureCallback`, `kill`, `memoryUsage`, `noDeprecation`, `permission`, `ref`, `release`, `report`, `resourceUsage`, `send`, `setUncaughtExceptionCaptureCallback`, `sourceMapsEnabled`, `threadCpuUsage`, `throwDeprecation`, `traceDeprecation`, `unref`. From e13577887c69755c32e9866748a689c0d5a570f7 Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Thu, 4 Sep 2025 11:32:14 -0700 Subject: [PATCH 6/7] Update title --- src/content/docs/workers/runtime-apis/nodejs/process.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index 830842e838475f..da6ad1cf50bdd0 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -94,7 +94,7 @@ The line buffer works by storing writes to stdout or stderr until either a newli This ensures compatibility with inspector and structured logging outputs. -## Filesystem +## Current Working Directory [`process.cwd()`](https://nodejs.org/docs/latest/api/process.html#processcwd) is the _current workding directory_, used as the default path for all filesystem operations, and is initialized to `/bundle`. From 6b9c003182572a78998c0e8253824956605a542b Mon Sep 17 00:00:00 2001 From: Guy Bedford Date: Sun, 14 Sep 2025 22:36:56 -0700 Subject: [PATCH 7/7] update stdio doc --- src/content/docs/workers/runtime-apis/nodejs/process.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/process.mdx b/src/content/docs/workers/runtime-apis/nodejs/process.mdx index da6ad1cf50bdd0..d6371279323867 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/process.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/process.mdx @@ -87,8 +87,7 @@ nextTick(() => { ## Stdio [`process.stdout`](https://nodejs.org/docs/latest/api/process.html#processstdout), [`process.stderr`](https://nodejs.org/docs/latest/api/process.html#processstderr) and [`process.stdin`](https://nodejs.org/docs/latest/api/process.html#processstdin) are supported as streams. `stdin` is treated as an empty readable stream. -`stdout` and `stderr` are treated as non-TTY writable streams, with line buffering when integrating with inspector and structured -logging output. +`stdout` and `stderr` are non-TTY writable streams, which output to normal logging output only with `stdout: ` and `stderr: ` prefixing. The line buffer works by storing writes to stdout or stderr until either a newline character `\n` is encountered or until the next microtask, when the log is then flushed to the output.