feat(unenv-preset): add native node:worker_threads module support by petebacondarwin · Pull Request #12043 · cloudflare/workers-sdk

petebacondarwin · 2026-01-22T11:22:36Z

Adds support for the native node:worker_threads module from workerd when both the enable_nodejs_worker_threads_module and experimental compatibility flags are enabled. This follows the same pattern as other experimental modules (repl).

Implementation Comparison

Export	workerd	unenv	Breaking change?
`MessageChannel`	`globalThis.MessageChannel` (native Web API)	Custom stub class	No - both export as function
`MessagePort`	`globalThis.MessagePort` (native Web API)	Custom stub class	No - both export as function
`BroadcastChannel`	throws `ERR_METHOD_NOT_IMPLEMENTED`	No-op stub class	Potential - constructor now throws
`Worker`	throws `ERR_METHOD_NOT_IMPLEMENTED`	No-op stub class	Potential - constructor now throws
`getEnvironmentData` / `setEnvironmentData`	Map-based	Map-based	No (same behavior)
`isMainThread`, `parentPort`, `threadId`, `workerData`, `resourceLimits`	Same values	Same values	No
`SHARE_ENV`	Same symbol	Same symbol	No
`postMessageToThread`	throws `ERR_METHOD_NOT_IMPLEMENTED`	throws "not implemented"	No (both throw)
`isInternalThread`	`false`	`false`	No

Breaking change analysis: The main behavioral differences are that Worker and BroadcastChannel constructors now throw ERR_METHOD_NOT_IMPLEMENTED instead of returning no-op instances. This is more correct behavior and uses proper Node.js error codes.

Implementation Notes

The test uses getRuntimeFlagValue("enable_nodejs_worker_threads_module") to detect native implementation at runtime (not export sniffing)

Human Review Checklist

Verify the getWorkerThreadsOverrides() function follows the same pattern as other experimental modules (requires experimental flag)
Confirm the compatibility flag names match workerd's compatibility-date.capnp (enable_nodejs_worker_threads_module / disable_nodejs_worker_threads_module)
Review the test coverage for both unenv stub and native workerd implementations
Verify native detection uses getRuntimeFlagValue() instead of sniffing exports

Link to Devin run

Tests
- Tests included/updated
- Automated tests not possible - manual testing has been completed as follows:
- Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: internal experimental feature, follows existing patterns

devin-ai-integration · 2026-01-22T11:22:41Z

🤖 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 that start with 'DevinAI' or '@devin'.
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 · 2026-01-22T11:22:41Z

🦋 Changeset detected

Latest commit: 3a9da95

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

pkg-pr-new · 2026-01-22T11:26:08Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@12043

wrangler

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

commit: 3a9da95

claude · 2026-01-28T16:45:28Z

Claude finished @petebacondarwin's task —— View job

Changeset Review

Reviewing changeset files...

Read changeset guidelines
Review .changeset/native-worker-threads.md
Validate against criteria
Post findings

✅ All changesets look good

The changeset .changeset/native-worker-threads.md follows all guidelines:

Version Type: ✅ Minor is correct - this is a new feature
Changelog Quality: ✅ Clear description with explicit note about experimental nature and required flags
Markdown Headers: ✅ No h1/h2/h3 headers used
Analytics: ✅ N/A - no analytics collection changes
Dependabot: ✅ N/A - not a dependency update
Experimental features: ✅ Includes explicit note about experimental status and required compatibility flags (nodejs_compat, experimental, and enable_nodejs_worker_threads_module)

.changeset/native-worker-threads.md

packages/wrangler/e2e/unenv-preset/worker/index.ts

… flag The node:worker_threads module was previously importing MessageChannel and MessagePort from globalThis, which meant it only worked when the expose_global_message_channel compatibility flag was enabled. This change introduces a new internal module (cloudflare-internal:messagechannel) that exposes MessageChannel and MessagePort for use by built-in modules, independent of the global flag. Changes: - Add MessageChannelModule C++ class in messagechannel.h - Register cloudflare-internal:messagechannel as an internal module - Update node:worker_threads to import from the internal module - Add TypeScript type definitions for the internal module - Remove expose_global_message_channel from worker_threads tests This unblocks cloudflare/workers-sdk#12043 which needs worker_threads to work without requiring the global flag.

petebacondarwin · 2026-02-13T13:08:07Z

Blocked on cloudflare/workerd#6069

petebacondarwin · 2026-02-17T10:26:15Z

Blocked on cloudflare/workerd#6069

This landed in v1.20260214.0 and main is already up to date with this, so now unblocked.

vicb

I that the thing you changed in worked recently?
So we need a peer dep bump?
Otherwise LGTM

petebacondarwin · 2026-02-17T14:30:27Z

I that the thing you changed in worked recently? So we need a peer dep bump? Otherwise LGTM

Oops! Good spot @vicb - I forgot that it was not enough to update workerd in general, we need to bump the peer dep. Will add that now.

petebacondarwin · 2026-02-17T14:31:03Z

This is the change:

Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

Co-Authored-By: [email protected] <[email protected]>

…y all workerd versions) Co-Authored-By: [email protected] <[email protected]>

… differences Co-Authored-By: [email protected] <[email protected]>

Co-Authored-By: [email protected] <[email protected]>

…mpatibility Co-Authored-By: [email protected] <[email protected]>

…reads feature Co-Authored-By: [email protected] <[email protected]>

Co-Authored-By: [email protected] <[email protected]>

- Both workerd and unenv export MessageChannel, MessagePort, Worker, BroadcastChannel - Use getRuntimeFlagValue() to check if native workerd is enabled - Test behavioral differences (Worker/BroadcastChannel throw in native workerd) Co-Authored-By: [email protected] <[email protected]>

- Native workerd exports MessageChannel/MessagePort as globalThis refs which may be undefined - Split type assertions for native vs unenv stub implementations - Only test MessageChannel in unenv stub mode Co-Authored-By: [email protected] <[email protected]>

Co-Authored-By: [email protected] <[email protected]>

…erd) Co-Authored-By: [email protected] <[email protected]>

Co-Authored-By: [email protected] <[email protected]>

This actually now fails because the MessageChannel in the `node:worker_threads` module is pulled from the `global.MessageChannel` and that is only available if `expose_global_message_channel` compat flag is on...

@petebacondarwin

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

@petebacondarwin

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

@petebacondarwin

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

@petebacondarwin

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

devin-ai-integration bot assigned petebacondarwin Jan 22, 2026

workers-devprod added this to workers-sdk Jan 22, 2026

github-project-automation bot moved this to Untriaged in workers-sdk Jan 22, 2026

vicb mentioned this pull request Jan 28, 2026

native node:* modules implemented in workerd #10594

Open

This comment was marked as resolved.

Sign in to view

petebacondarwin commented Feb 2, 2026

View reviewed changes

.changeset/native-worker-threads.md Outdated Show resolved Hide resolved

petebacondarwin commented Feb 2, 2026

View reviewed changes

packages/wrangler/e2e/unenv-preset/worker/index.ts Outdated Show resolved Hide resolved

petebacondarwin force-pushed the devin/1769080195-native-node-worker-threads branch from 95b868a to 949c436 Compare February 11, 2026 11:47

petebacondarwin mentioned this pull request Feb 13, 2026

Make node:worker_threads independent of expose_global_message_channel flag cloudflare/workerd#6069

Merged

petebacondarwin added blocked Blocked on other work unenv labels Feb 13, 2026

petebacondarwin force-pushed the devin/1769080195-native-node-worker-threads branch from a5bfd5b to ce12ada Compare February 17, 2026 09:37

petebacondarwin marked this pull request as ready for review February 17, 2026 09:47

petebacondarwin requested a review from a team as a code owner February 17, 2026 09:47

This comment was marked as resolved.

Sign in to view

petebacondarwin removed the blocked Blocked on other work label Feb 17, 2026

This comment was marked as duplicate.

Sign in to view

vicb approved these changes Feb 17, 2026

View reviewed changes

github-project-automation bot moved this from Untriaged to Approved in workers-sdk Feb 17, 2026

devin-ai-integration bot and others added 2 commits February 17, 2026 14:34

feat(unenv-preset): add native node:worker_threads module support

049ed94

Co-Authored-By: [email protected] <[email protected]>

fix: remove expectRuntimeFlags for worker_threads (flag not exposed b…

a2dadc1

…y all workerd versions) Co-Authored-By: [email protected] <[email protected]>

devin-ai-integration bot and others added 17 commits February 17, 2026 14:34

fix: update testWorkerThreads to handle native workerd implementation…

b1cefa9

… differences Co-Authored-By: [email protected] <[email protected]>

fix: detect native worker_threads by checking MessageChannel export

fde4d22

Co-Authored-By: [email protected] <[email protected]>

fix: skip MessageChannel test in native workerd (not available)

9ec6644

Co-Authored-By: [email protected] <[email protected]>

fix: add experimental flag to worker_threads tests for remote test co…

9c3bc64

…mpatibility Co-Authored-By: [email protected] <[email protected]>

docs: add opt-in instructions to changeset for experimental worker_th…

ff84118

…reads feature Co-Authored-By: [email protected] <[email protected]>

fix: require experimental flag for worker_threads like repl

ebf80b2

Co-Authored-By: [email protected] <[email protected]>

Apply suggestion from @petebacondarwin

c40485a

fix: update worker_threads test comments to use TODO pattern

944bb7a

Co-Authored-By: [email protected] <[email protected]>

fix: always check MessageChannel/MessagePort (native Web APIs in work…

b70ec60

…erd) Co-Authored-By: [email protected] <[email protected]>

fix: use native MessageChannel Web API instead of module export

647da1e

Co-Authored-By: [email protected] <[email protected]>

fix: conditionally test MessageChannel for older compatibility dates

7e69135

Co-Authored-By: [email protected] <[email protected]>

update changeset

2ff89d0

Use non-global MessageChannel in worker_threads test

b857afc

This actually now fails because the MessageChannel in the `node:worker_threads` module is pulled from the `global.MessageChannel` and that is only available if `expose_global_message_channel` compat flag is on...

Add missing expectRuntimeFlags to worker_threads test configs

a29714e

bump the peer dependency to require the fixed version of workerd

2a78e21

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

petebacondarwin force-pushed the devin/1769080195-native-node-worker-threads branch from 5d7060a to 2a78e21 Compare February 17, 2026 14:34

This comment was marked as resolved.

Sign in to view

petebacondarwin added 3 commits February 17, 2026 15:05

bump the peer dependency to require the fixed version of workerd

c980e14

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

bump the peer dependency to require the fixed version of workerd

d09e11c

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

bump the peer dependency to require the fixed version of workerd

3a9da95

> Make node:worker_threads independent of expose_global_message_channel flag by @petebacondarwin in cloudflare/workerd#6069

petebacondarwin merged commit 452cdc8 into main Feb 17, 2026
47 of 49 checks passed

petebacondarwin deleted the devin/1769080195-native-node-worker-threads branch February 17, 2026 17:11

github-project-automation bot moved this from Approved to Done in workers-sdk Feb 17, 2026

workers-devprod mentioned this pull request Feb 17, 2026

Version Packages #12580

Merged

Comments

Conversation

petebacondarwin commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementation Comparison

Implementation Notes

Human Review Checklist

Uh oh!

devin-ai-integration bot commented Jan 22, 2026

🤖 Devin AI Engineer

Uh oh!

changeset-bot bot commented Jan 22, 2026 • 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 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

claude bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changeset Review

Uh oh!

Uh oh!

Uh oh!

petebacondarwin commented Feb 13, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

petebacondarwin commented Feb 17, 2026

Uh oh!

This comment was marked as duplicate.

Uh oh!

vicb left a comment

Choose a reason for hiding this comment

Uh oh!

petebacondarwin commented Feb 17, 2026

Uh oh!

petebacondarwin commented Feb 17, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

petebacondarwin commented Jan 22, 2026 •

edited

Loading

changeset-bot bot commented Jan 22, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 22, 2026 •

edited

Loading

claude bot commented Jan 28, 2026 •

edited

Loading