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

petebacondarwin · 2025-12-18T15:06:38Z

Similar to #10621 (native vm module support), this PR adds support for the native node:dgram module when the enable_nodejs_dgram_module compatibility flag is enabled.

Since dgram is marked as $experimental in workerd with no $impliedByAfterDate, this feature requires both the enable_nodejs_dgram_module and experimental compatibility flags to be set.

Updates since last revision

Fixed enabledByFlag to also check for the experimental compatibility flag, ensuring the native module is only enabled when both flags are present (per reviewer feedback)
Bumped workerd peer dependency to ^1.20251221.0 which includes the dgram fix from cloudflare/workerd#5729

Implementation Comparison

The three dgram implementations differ significantly:

Node.js (full implementation): Complete UDP socket support with native bindings (udp_wrap), proper state management, event emission, multicast/broadcast support, and integration with diagnostics_channel and async_hooks.

workerd (non-functional stub): Exports the expected API surface (Socket, createSocket) but core methods throw ERR_METHOD_NOT_IMPLEMENTED. Configuration methods like setBroadcast(), setTTL() are no-ops. This is intentional as UDP is not supported in the Workers runtime.

unenv (soft stub polyfill): Returns a concrete Socket instance so code paths don't immediately throw. Methods are mostly chainable no-ops returning placeholder values (e.g., getRecvBufferSize() returns 100,000).

When the native module is enabled, workerd's implementation is used instead of unenv's polyfill.

⚠️ Potential Breaking Change

Update: The breaking change concern has been addressed in cloudflare/workerd#5729, which is included in workerd 1.20251221.0 (the new minimum peer dependency version).

When enabling the native dgram module, code that previously relied on unenv's silent no-op behavior may break because workerd throws errors instead:

Method	unenv behavior	workerd behavior
`createSocket()`	Returns `Socket` instance	Throws `ERR_METHOD_NOT_IMPLEMENTED`
`Socket()` constructor	Returns `Socket` instance	Throws `ERR_METHOD_NOT_IMPLEMENTED`
`bind()`	Returns `this` (no-op)	Throws `ERR_METHOD_NOT_IMPLEMENTED`
`connect()`	No-op	Throws `ERR_METHOD_NOT_IMPLEMENTED`
`send()`	No-op	Throws `ERR_METHOD_NOT_IMPLEMENTED`
`close()`	Returns `this` (no-op)	Throws `ERR_METHOD_NOT_IMPLEMENTED`

This is opt-in via the experimental flag, so existing code is unaffected unless users explicitly enable enable_nodejs_dgram_module.

Human Review Checklist

Verify flag names match workerd's compatibility-date.capnp
Verify pattern matches other experimental modules (wasi)
Tests include experimental flag as required
enabledByFlag checks for both enable_nodejs_dgram_module AND experimental flags
Confirm tests only validate API surface (not actual UDP functionality, since workerd's dgram is a stub)
Review breaking change table for accuracy
Verify workerd 1.20251221.0 includes the dgram fix from workerd#5729

Devin PR requested by @petebacondarwin
Link to Devin run: https://app.devin.ai/sessions/b61a9f009eec4b03850a418e63f16687

Tests
- Tests included/updated
- Tests not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: dgram is already documented as partially supported in the Workers docs
Wrangler V3 Backport
- Wrangler PR:
- Not necessary because: this is a minor feature addition to unenv-preset, not a patch fix

changeset-bot · 2025-12-18T15:06:43Z

🦋 Changeset detected

Latest commit: 919cf40

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

devin-ai-integration · 2025-12-18T15:06:43Z

🤖 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

claude · 2025-12-18T15:07:06Z

Claude finished @petebacondarwin's task —— View job

Changeset Review

✅ All changesets look good

The changeset .changeset/native-dgram-module.md is properly formatted:

✅ Version Type: Correctly set as minor (new feature for experimental functionality)
✅ No Markdown Headers: No h1/h2/h3 headers present
✅ Clear Description: Concise explanation of the feature and flag requirements
✅ Package: Correctly targets @cloudflare/unenv-preset

Note: The reviewer (vicb) suggested simplifying the changeset description to remove explanatory content about what dgram is and examples, as they felt it was misleading without the nodejs_compat flag context. The current version is already quite minimal and focused on the core functionality being added. If further simplification is desired, that can be done at merge time.

pkg-pr-new · 2025-12-18T15:10:22Z

create-cloudflare

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

@cloudflare/kv-asset-handler

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

miniflare

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

@cloudflare/pages-shared

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

@cloudflare/unenv-preset

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

@cloudflare/vite-plugin

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

@cloudflare/vitest-pool-workers

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

@cloudflare/workers-editor-shared

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

@cloudflare/workers-utils

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

wrangler

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

commit: 919cf40

petebacondarwin · 2025-12-19T11:51:12Z

See cloudflare/workerd#5729 for update to workerd to avoid breaking changes

devin-ai-integration · 2025-12-19T11:53:13Z

Thanks for the update! Once cloudflare/workerd#5729 lands, the breaking change concern will be resolved since workerd's dgram implementation will return no-ops instead of throwing ERR_METHOD_NOT_IMPLEMENTED. I'll update the PR description to reference this.

vicb · 2025-12-22T10:14:48Z

+		"disable_nodejs_dgram_module"
+	);
+
+	const enabledByFlag = compatibilityFlags.includes(


We should also test for experimental here

vicb

Looks good once we test for experimental as well.

Thanks Pete!

vicb · 2025-12-22T10:35:41Z

@petebacondarwin could you please bump the workerd peer dep to whatever workerd first get your corresponding PR?

vicb · 2026-01-06T14:28:02Z

+To enable the native dgram module, add the following to your `wrangler.jsonc`:
+
+```jsonc
+{
+	"compatibility_flags": ["experimental", "enable_nodejs_dgram_module"],
+}
+```


Maybe drop this, it is misleading without the nodejs_compat flag

vicb

LGTM - maybe simplify the changeset?

vicb · 2026-01-09T06:48:18Z

rebased on main

vicb · 2026-01-13T15:27:24Z

Just rebased + fixed lock file

Add getDgramOverrides() function to enable native dgram module support when the enable_nodejs_dgram_module compatibility flag is set. This feature is experimental and requires both the enable_nodejs_dgram_module and experimental compatibility flags to be enabled. Includes E2E tests for enable/disable flag behavior. Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

Add getDgramOverrides() function to enable native dgram module support when the enable_nodejs_dgram_module compatibility flag is set. This feature is experimental and requires both the enable_nodejs_dgram_module and experimental compatibility flags to be enabled. Includes E2E tests for enable/disable flag behavior. Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

workers-devprod added this to workers-sdk Dec 18, 2025

github-project-automation Bot moved this to Untriaged in workers-sdk Dec 18, 2025

petebacondarwin commented Dec 18, 2025

View reviewed changes

Comment thread .changeset/native-dgram-module.md Outdated

petebacondarwin force-pushed the devin/1766069673-dgram-native-module branch from 67aa169 to b2fa5db Compare December 19, 2025 08:46

petebacondarwin added the blocked Blocked on other work label Dec 19, 2025

vicb mentioned this pull request Dec 20, 2025

native node:* modules implemented in workerd #10594

Closed

petebacondarwin added the nodejs compat Relating to the node runtime compatibility flag label Dec 20, 2025

petebacondarwin force-pushed the devin/1766069673-dgram-native-module branch from b2fa5db to 73b3129 Compare December 22, 2025 07:23

petebacondarwin marked this pull request as ready for review December 22, 2025 08:41

petebacondarwin requested a review from a team as a code owner December 22, 2025 08:41

petebacondarwin force-pushed the devin/1766069673-dgram-native-module branch from 73b3129 to 0cd1038 Compare December 22, 2025 08:41

vicb reviewed Dec 22, 2025

View reviewed changes

Comment thread packages/unenv-preset/src/preset.ts Outdated

vicb approved these changes Dec 22, 2025

View reviewed changes

github-project-automation Bot moved this from Untriaged to Approved in workers-sdk Dec 22, 2025

petebacondarwin force-pushed the devin/1766069673-dgram-native-module branch from 3db3bce to 2dfa363 Compare January 6, 2026 13:38

vicb reviewed Jan 6, 2026

View reviewed changes

Comment thread .changeset/native-dgram-module.md Outdated

vicb approved these changes Jan 6, 2026

View reviewed changes

vicb force-pushed the devin/1766069673-dgram-native-module branch from c5062f4 to 8f06777 Compare January 9, 2026 06:46

vicb force-pushed the devin/1766069673-dgram-native-module branch from d66d5df to 48f62e1 Compare January 13, 2026 15:27

devin-ai-integration Bot and others added 8 commits January 13, 2026 18:31

docs: add usage example to changeset for dgram module

32ab03d

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

docs: use JSONC format for wrangler config in changeset

6f5efd0

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

fix: require experimental flag for dgram module enablement

6669bac

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

chore: bump workerd peer dependency to 1.20251221.0

472ee46

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

docs: simplify dgram changeset per review feedback

cc18b48

Co-Authored-By: pbacondarwin@cloudflare.com <pete@bacondarwin.com>

fixup! lock file

919cf40

petebacondarwin force-pushed the devin/1766069673-dgram-native-module branch from 48f62e1 to 919cf40 Compare January 13, 2026 18:31

vicb merged commit fec8f5b into main Jan 13, 2026
39 of 41 checks passed

vicb deleted the devin/1766069673-dgram-native-module branch January 13, 2026 19:56

github-project-automation Bot moved this from Approved to Done in workers-sdk Jan 13, 2026

workers-devprod mentioned this pull request Jan 13, 2026

Version Packages #11903

Merged

Conversation

petebacondarwin commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Updates since last revision

Implementation Comparison

⚠️ Potential Breaking Change

Human Review Checklist

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

devin-ai-integration Bot commented Dec 18, 2025

🤖 Devin AI Engineer

Uh oh!

claude Bot commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changeset Review

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

petebacondarwin commented Dec 19, 2025

Uh oh!

devin-ai-integration Bot commented Dec 19, 2025

Uh oh!

vicb Dec 22, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vicb left a comment

Choose a reason for hiding this comment

Uh oh!

vicb commented Dec 22, 2025

Uh oh!

vicb Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

vicb left a comment

Choose a reason for hiding this comment

Uh oh!

vicb commented Jan 9, 2026

Uh oh!

vicb commented Jan 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

petebacondarwin commented Dec 18, 2025 •

edited

Loading

changeset-bot Bot commented Dec 18, 2025 •

edited

Loading

claude Bot commented Dec 18, 2025 •

edited

Loading

pkg-pr-new Bot commented Dec 18, 2025 •

edited

Loading