Use workerd `node:process` v2 when available by vicb · Pull Request #10577 · cloudflare/workers-sdk

vicb · 2025-09-08T14:20:43Z

This PR enabled using workerd node:process v2 when it is enabled (by flag or date).

It depends on the implemntation being available:

implemented in Remove experimental for node:process workerd#4960
releases in workerd v1.20250904.0
depends on Implement all process exports as stubbed or unimplemented workerd#5040 released in https://github.com/cloudflare/workerd/releases/tag/v1.20250911.0
depends on Use stdio log prefixing for process.stdio workerd#5024 released in https://github.com/cloudflare/workerd/releases/tag/v1.20250912.0

Outdated comment:

Details

A few notes:

This PR still fails the remote tests as the v2 changes have not reached production yet.

Some of the v2 APIs are undefined.

For that reason we still need an hybrid polyfill pulling their implementation from unenv. Otherwise the following code might break:

import { process } from "node:process";

// This would break with v2 as `process.release` is `undefined.
console.log(process.release.name);

Because we have to use an hybrid polyfill anyway, we keep all the APIs that are implemented in unenv and missing from workerd:

_... APIs (_channel, _debugEnd, ...)
some other APIs as addListener, assert, ...

addListener, assert, ... are not all documented on nodejs.org and a few are deprecated. But they all are available for Node 22.16.0 (tested in the REPL).

Maybe we can refine and better handle deprecated APIs now that we have a dedicated workerd flag. Comments welcome.

@petebacondarwin @guybedford could you please review the PR, the API surface is quite large and having more eyes would be helpful.

Tests
- Tests included
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: will be documented by the runtime team
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: unenv changes are not backported

changeset-bot · 2025-09-08T14:20:48Z

🦋 Changeset detected

Latest commit: 24047d6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/unenv-preset	Patch
@cloudflare/vite-plugin	Patch
wrangler	Patch
@cloudflare/vitest-pool-workers	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-09-08T14:23:13Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@10577

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@10577

miniflare

npm i https://pkg.pr.new/miniflare@10577

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@10577

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@10577

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@10577

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@10577

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@10577

wrangler

npm i https://pkg.pr.new/wrangler@10577

commit: 24047d6

guybedford · 2025-09-08T16:24:13Z

I believe that in most of the cases where unenv is providing an implementation of a function like process.binding() and where we are providing undefined - the implementation is simply a throwing stub. Simply copying over the throwing stub should be just a couple of lines and might get far to enabling a non-hybrid approach.

For undocumented APIs, I notice _debugEnd is implemented by Bun but not Deno. Do we definitely need these?

For non-function bindings, like process.release - having an upstream issue to track their support would be a huge help. Happy to fill gaps as necessary as well.

vicb · 2025-09-08T19:54:00Z

I believe that in most of the cases where unenv is providing an implementation of a function like process.binding() and where we are providing undefined - the implementation is simply a throwing stub. Simply copying over the throwing stub should be just a couple of lines and might get far to enabling a non-hybrid approach.

When you say "Simply copying over the throwing stub [...]" do you mean copying the implementation to workerd?

If you rather mean copying the implementation to the unev preset in this repo then that would still be an hybrid polyfill and I don't really see the point?

For undocumented APIs, I notice _debugEnd is implemented by Bun but not Deno. Do we definitely need these?

I agree that the likeness those _... APIs are used is low but we have no way to definitely rule out that they are not.
And because we need an hybrid polyfill anyway there should be no good reason to remove them?

For non-function bindings, like process.release - having an upstream issue to track their support would be a huge help. Happy to fill gaps as necessary as well.

Sorry, I'm not exactly sure where you'd want to create the issue and what the content should be. Feel free to start someone and I'll contribute if needed.

guybedford · 2025-09-11T00:11:52Z

Thanks again for working on this. Happy to review further. We just landed comprehensive process stubs in cloudflare/workerd#5040 which may help the transition here when that is available.

vicb · 2025-09-15T13:59:35Z

I did sync after the update of workerd in wrangler.

@petebacondarwin and @guybedford could you please review this PR?

guybedford

Left an initial review. I'll look into an upstream follow-up for _eventsCount, _maxListeners and _events as well.

guybedford · 2025-09-15T16:10:44Z

packages/unenv-preset/src/runtime/node/process.ts

These are now all implemented in cloudflare/workerd#5040.

Same comment as on line 106

guybedford · 2025-09-15T16:11:09Z

packages/unenv-preset/src/runtime/node/process.ts

These are also now added in cloudflare/workerd#5040.

See the comment line 64 and line 181

// API that are only implemented starting from v2 of workerd process // They are retrieved from unenv when process v1 is used export const { [...] } = isWorkerdProcessV2 ? workerdProcess : unenvProcess;

I think the code is right. Am I missing something?

guybedford · 2025-09-15T16:17:20Z

packages/unenv-preset/src/runtime/node/process.ts

I think it would be fine to leave these ones out at this point, or have a path to test that. In Node.js,

import * as process from 'node:process'; console.log('process._channel', '_channel' in process, process._channel); // ...

Gives:

process._channel false undefined process._disconnect false undefined process._events true [Object: null prototype] { newListener: [ [Function (anonymous)], [Function: startListeningIfSignal] ], removeListener: [ [Function (anonymous)], [Function: stopListeningIfSignal] ], warning: [Function: onWarning], SIGWINCH: [ [Function: refreshStdoutOnSigWinch], [Function: refreshStderrOnSigWinch] ] } process._eventsCount true 3 process._handleQueue false undefined process._maxListeners true undefined process._pendingMessage false undefined process._send false undefined process.assert false undefined process.disconnect false undefined process.mainModule false undefined

Maintaining compat that is just not Node.js doesn't make sense to me.

Where _eventsCount, _maxListeners and _events are thus the only ones worth even considering keeping here.

In Node.js

In what version of Node.js ?

At least we know that they were there before so let's merge this now and cleanup later.

WDYT?

packages/wrangler/e2e/unenv-preset/preset.test.ts

vicb · 2025-09-15T20:33:00Z

packages/unenv-preset/src/runtime/node/process.ts

domain should be updated here and below

vicb · 2025-09-15T20:34:54Z

Left an initial review. I'll look into an upstream follow-up for _eventsCount, _maxListeners and _events as well.

I think it's ok to address those in a follow up PR because this should be merged soonish (merging in workerd, doing a release, updating workerd in this repo will take 2/3 days if everything goes well).

Any objection?

guybedford

Sure, absolutely makes sense to roll this one out sooner rather than later.

vicb · 2025-09-15T21:34:08Z

Rebased + added a fixup commit for comments only

vicb requested a review from a team as a code owner September 8, 2025 14:20

vicb requested a review from a team September 8, 2025 14:20

vicb added the skip-pr-description-validation Skip validation of the required PR description format label Sep 8, 2025

workers-devprod added this to workers-sdk Sep 8, 2025

github-project-automation bot moved this to Untriaged in workers-sdk Sep 8, 2025

vicb added skip-v3-pr and removed skip-pr-description-validation Skip validation of the required PR description format labels Sep 8, 2025

vicb force-pushed the vicb/unenv-process branch 2 times, most recently from 4967ba8 to c94f131 Compare September 9, 2025 07:18

petebacondarwin mentioned this pull request Sep 9, 2025

process.stderr to use console.debug, with DEBUG level to stderr cloudflare/workerd#4965

Closed

vicb mentioned this pull request Sep 9, 2025

native node:* modules implemented in workerd #10594

Closed

petebacondarwin force-pushed the vicb/unenv-process branch from c94f131 to 0baeb4a Compare September 10, 2025 07:37

petebacondarwin mentioned this pull request Sep 10, 2025

Support console.debug on stderr #10560

Closed

6 tasks

petebacondarwin force-pushed the vicb/unenv-process branch 3 times, most recently from 0782e55 to 57ed746 Compare September 10, 2025 19:40

vicb changed the title ~~Use workerd node:process v2 when available~~ [BLOCKED on workerd release] Use workerd node:process v2 when available Sep 11, 2025

petebacondarwin added the blocked Blocked on other work label Sep 11, 2025

petebacondarwin marked this pull request as draft September 11, 2025 11:31

vicb force-pushed the vicb/unenv-process branch from 57ed746 to 245574e Compare September 15, 2025 13:56

vicb changed the title ~~[BLOCKED on workerd release] Use workerd node:process v2 when available~~ *Use workerd node:process v2 when available Sep 15, 2025

vicb changed the title *Use workerd node:process v2 when available Use workerd node:process v2 when available Sep 15, 2025

vicb marked this pull request as ready for review September 15, 2025 13:57

petebacondarwin approved these changes Sep 15, 2025

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Sep 15, 2025

guybedford reviewed Sep 15, 2025

View reviewed changes

vicb commented Sep 15, 2025

View reviewed changes

packages/unenv-preset/src/runtime/node/process.ts Outdated

Copy link
Copy Markdown

Contributor Author

vicb Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

domain should be updated here and below

guybedford approved these changes Sep 15, 2025

View reviewed changes

vicb and others added 4 commits September 15, 2025 23:33

Use workerd node:process v2 when available

adbed07

fixup! use API implemented in workerd #5040

efb0557

update worker-log tests to account for nodejs compat process v2 flag

6449b80

fixup! comments

24047d6

vicb force-pushed the vicb/unenv-process branch from 245574e to 24047d6 Compare September 15, 2025 21:33

dario-piotrowicz merged commit e9b0c66 into main Sep 16, 2025
42 of 50 checks passed

github-project-automation bot moved this from Approved to Done in workers-sdk Sep 16, 2025

dario-piotrowicz deleted the vicb/unenv-process branch September 16, 2025 12:59

workers-devprod mentioned this pull request Sep 16, 2025

Version Packages #10672

Merged

Conversation

vicb commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Sep 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

guybedford commented Sep 8, 2025

Uh oh!

vicb commented Sep 8, 2025

Uh oh!

guybedford commented Sep 11, 2025

Uh oh!

vicb commented Sep 15, 2025

Uh oh!

guybedford left a comment

Choose a reason for hiding this comment

Uh oh!

guybedford Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

vicb Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

guybedford Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

vicb Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

guybedford Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

vicb Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vicb Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

vicb commented Sep 15, 2025

Uh oh!

guybedford left a comment

Choose a reason for hiding this comment

Uh oh!

vicb commented Sep 15, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

vicb commented Sep 8, 2025 •

edited

Loading

changeset-bot bot commented Sep 8, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 8, 2025 •

edited

Loading