Use the native node:domain module when available

[devin-ai-integration]

Adds support for using the native node:domain module from workerd when available, following the pattern established in previous module conversion PRs.

This is the first PR in a series to convert 9 remaining Node.js modules from unenv polyfills to native workerd implementations.

Changes

• Added getDomainOverrides() function to enable/disable the native domain module based on compatibility flags
• Integrated domain overrides into the preset system (both nativeModules and hybridModules)
• Added E2E tests for enable/disable flag behavior
• Requires experimental flag and enable_nodejs_domain_module flag to enable
• Can be disabled with disable_nodejs_domain_module flag

Key Differences: workerd vs unenv

The workerd implementation has a more complete Domain API surface with all methods (enter, exit, add, remove, run, intercept, bind) compared to unenv's basic implementation. Both implementations are non-functional stubs, but workerd throws explicit ERR_METHOD_NOT_IMPLEMENTED errors and has better validation.

Review Focus

• Verify flag naming follows convention: enable_nodejs_domain_module / disable_nodejs_domain_module
• Confirm implementation matches the pattern from cluster/punycode modules
• Check test coverage is consistent with existing module tests

---

Link to Devin run: https://app.devin.ai/sessions/f2a8f635e47b47e8baa9bc1b68af0635
Requested by: @petebacondarwin ([email protected])

---

• Tests
  • Tests included
• Public documentation
  • Documentation not necessary because: this is an experimental feature requiring the experimental flag
• Wrangler V3 Backport
  • Not necessary because: unenv-preset changes are never backported to v3

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[changeset-bot]

🦋 Changeset detected

Latest commit: 2c83c3d

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

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

[github-actions]

Failed to automatically backport this PR's changes to Wrangler v3. Please manually create a PR targeting the v3-maintenance branch with your changes. Thank you for helping us keep Wrangler v3 supported!

Depending on your changes, running git rebase --onto v3-maintenance main devin/1760950875-node-domain might be a good starting point.

Notes:

• your PR branch should be named v3-backport-11023
• add the skip-v3-pr label to the current PR to stop this workflow from failing

[pkg-pr-new]

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

wrangler

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

commit: 2c83c3d

[petebacondarwin]

Note that the active export is different between the native and polyfill with the unenv polyfill being incorrect (AFAICT):

unenv:

export const active = () => _domain;

workerd:

// The active domain is always the one that we're currently in.
export const active: Domain | null = null;

nodejs:

// The active domain is always the one that we're currently in.
exports.active = null;

[petebacondarwin]

Note that workerd does not export the internal undocumented _stack array. I think this is an acceptable expectation and not breaking since this should not be used externally. It is only exported from the module in the Node.js codebase for internal testing purposes.

[devin-ai-integration]

Thanks for documenting these differences! You're right that:

1. The active export difference is actually a correction - workerd matches Node.js behavior (property with null value) while unenv incorrectly implements it as a function
2. The missing _stack export is acceptable since it's an internal/undocumented API used only for Node.js testing

Both of these differences make workerd's implementation more correct/compatible with Node.js, which is the goal of this conversion.

[petebacondarwin]

Finally note that the Domain member property members is set to undefined in the class constructor for Domain in workerd, while it is set to [] in unenv.

But in the Node.js codebase it has a weird setup where the constructor sets the instance to [] but then there is this line:

Domain.prototype.members = undefined;

And elsewhere it is possible for member to be set to either [] or undefined. So I think that this difference is immaterial from a compatibility point of view and does not constitute a breaking change from unenv.

[petebacondarwin]

LGTM - @vicb should also take a view.

[vicb]

Changes LGTM.

[vicb]

Actually, the PR is missing basic tests for the domain module

[petebacondarwin]

Actually, the PR is missing basic tests for the domain module

😱 - you're absolutely right, I totally missed this.