src/node/ — Node.js Compatibility (TypeScript)

OVERVIEW

TypeScript and JavaScript layer implementing Node.js compatible built-in modules for Workers.

It is split across multiple layers:

1. An internal layer consisting of:
   • Non-user-importable TypeScript and JavaScript files in internal/ that implement core logic, utilities, and C++ JSG module declarations.
   • C++ JSG modules (src/workerd/api/node/) expose native ops via node-internal:* specifiers
   • Some native internal modules may be implemented in Rust
2. A public layer of TypeScript files at the top-level that are user-importable.

It is common, but not required, for top-level .ts files to re-export from internal/ via node-internal: specifiers. This allows for a clean separation between public API surface and internal implementation details.

See README.md for 12 policy rules governing compat scope and philosophy.

MODULE GATING

node:* modules are gated behind the nodejs_compat compatibility flag.

The node:async_hooks module can be enabled individually via the nodejs_als compatibility flag.

Runtime compat flags checked via Cloudflare.compatibilityFlags['flag_name']:

Flag	Guards
enable_nodejs_http_server_modules	http Server/createServer, https Server
nodejs_zlib	zlib streaming classes (Deflate, Gzip, etc.)
enable_nodejs_process_v2	Extended process/events functionality
remove_nodejs_compat_eol_v22/v23/v24	EOL deprecation of specific API surfaces (crypto, util, tls, process)

Most modules require nodejs_compat + nodejs_compat_v2 flags (enforced by C++ side, not visible here).

ADDING NEW INTERNAL MODULES

New .ts and .js files in internal/ are auto-discovered by the build system via glob(["internal/*.ts", "internal/*.js"]) in BUILD.bazel. No explicit registration is needed — just create the file and it becomes importable via its node-internal: specifier.

For example, creating internal/internal_fs_glob.ts immediately makes node-internal:internal_fs_glob available as an import specifier. No changes to BUILD.bazel or any registration macro are required.

What does require explicit wiring:

• New top-level node:* public modules need a corresponding .ts file in src/node/ and must be registered in the C++ module registry (src/workerd/api/node/node.h, the NODEJS_MODULES macro).
• New C++ JSG native modules require a .d.ts declaration file in internal/ to declare the shape of the native module.

CONVENTIONS

• internal/*.js (not .ts) = upstream Node.js ports (streams_readable.js, streams_writable.js, etc.); paired with .d.ts type declarations
• internal/*.d.ts without matching .ts = declares C++ JSG module shape (crypto.d.ts → node-internal:crypto)
• internal/*.d.ts with matching .js = types for ported JS (streams_readable.d.ts → streams_readable.js)
• Top-level files are thin: import from node-internal:*, re-export with export { ... } / export * from
• Feature-gated exports use if (!flag) { throw ... } or conditional class assignment patterns
• Shared validators in internal/validators.ts; shared errors in internal/internal_errors.ts
• _ prefix files (e.g., _http_agent.ts, _stream_readable.ts) = Node.js legacy internal module aliases
• Some Node.js compat APIs are non-functional stubs that are either non-ops or throw when called