From 84ea9fdefdf0568ab038ebf1b96fbf1c2c5f43ea Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Tue, 4 Mar 2025 20:58:07 -0800 Subject: [PATCH 1/2] Enumerate Node.js APIs on main Node.js docs page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit We don't currently have one place where you can look at-a-glance at what Node.js APIs are supported in Workers. The compatibility matrix here is very cool, overly detailed for a quick reference on what is or isn't supported: https://workers-nodejs-compat-matrix.pages.dev/ The clearest thing we can do is to provide a simple list of all non-deprecated, non-experimental APIs from Node.js (pulled this straight from the Node.js docs, in the same alphabetical order) — and state clearly which are supported, which we have partial support for, and which are not supported. And then link to our own relevant docs page. There are a few here that are currently supported, but we haven't yet added a docs page for. We'll need to follow up on this, so that the sidebar includes all of the Node.js APIs we currently support in the Workers Runtime. --- .../workers/runtime-apis/nodejs/index.mdx | 85 +++++++++++++------ 1 file changed, 61 insertions(+), 24 deletions(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index 7946952a7d9216..626a336f084209 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -12,14 +12,11 @@ When you write a Worker, you may need to import packages from [npm](https://www. Cloudflare Workers provides a subset of Node.js APIs in two forms: 1. As built-in APIs provided by the Workers Runtime -2. As polyfills that [Wrangler](/workers/wrangler/) adds to your Worker's code - -You can view which APIs are supported using the [Node.js compatibility matrix](https://workers-nodejs-compat-matrix.pages.dev). +2. As polyfill shim implementations that [Wrangler](/workers/wrangler/) adds to your Worker's code, allowing it to import the module, but calling API methods will throw errors. ## Get Started -To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your wrangler configuration. This also enables `nodejs_compat_v2` as long as your compatibility date is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). - +To enable built-in Node.js APIs and add polyfills, add the `nodejs_compat` compatibility flag to your [wrangler configuration file](/workers/wrangler/configuration/), and ensure that your Worker's [compatibility date](/workers/configuration/compatibility-dates/) is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). @@ -30,23 +27,68 @@ compatibility_date = "2024-09-23" -## Built-in Node.js Runtime APIs - -The following APIs from Node.js are provided directly by the Workers Runtime when either `nodejs_compat` or `nodejs_compat_v2` are enabled: +## Supported Node.js APIs + +The runtime APIs from Node.js listed below as "🟢 supported" are currently natively supported in the Workers Runtime. + +[Deprecated, experimental, and not yet stable APIs from Node.js](https://nodejs.org/docs/latest/api/documentation.html#stability-index) are not included as part of the list below: + +| API Name | Natively supported by the Workers Runtime | +|--------------------------------------------------------------------------------------|-------------------------------------------| +| [Assertion testing](/workers/runtime-apis/nodejs/assert/) | 🟢 supported | +| [Asynchronous context tracking](/workers/runtime-apis/nodejs/asynclocalstorage/) | 🟢 supported | +| [Buffer](/workers/runtime-apis/nodejs/buffer/) | 🟢 supported | +| C++ addons | ⚪ not supported | +| C/C++ addons with Node-API | ⚪ not supported | +| C++ embedder API | ⚪ not supported | +| Child processes | ⚪ not supported | +| Cluster | ⚪ not supported | +| Console | 🟢 supported | +| [Crypto](/workers/runtime-apis/nodejs/crypto/) | 🟡 partially supported | +| [Debugger](/workers/observability/dev-tools/) | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) | +| [Diagnostics Channel](/workers/runtime-apis/nodejs/diagnostics-channel/) | 🟢 supported | +| [DNS](/workers/runtime-apis/nodejs/dns/) | 🟢 supported | +| Errors | 🟢 supported | +| Events | 🟢 supported | +| File system | ⚪ not supported | +| Globals | 🟢 supported | +| HTTP | ⚪ not supported | +| HTTP/2 | ⚪ not supported | +| HTTPS | ⚪ not supported | +| Inspector | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) | +| [Net](/workers/runtime-apis/nodejs/net/) | 🟢 supported | +| OS | ⚪ not supported | +| [Path](/workers/runtime-apis/nodejs/path/) | 🟢 supported | +| Performance hooks | 🟡 partially supported | +| Process | 🟢 supported | +| Query strings | 🟢 supported | +| Readline | ⚪ not supported | +| Stream | 🟢 supported | +| [String decoder](/workers/runtime-apis/nodejs/string-decoder/) | 🟢 supported | +| Test runner | ⚪ not supported | +| [Timers](/workers/runtime-apis/nodejs/timers/) | 🟢 supported | +| TLS/SSL | ⚪ not supported | +| TTY | ⚪ not supported | +| UDP/datagram | ⚪ not supported | +| [URL](/workers/runtime-apis/nodejs/url/) | 🟢 supported | +| [Utilities](/workers/runtime-apis/nodejs/util/) | 🟢 supported | +| V8 | ⚪ not supported | +| VM | ⚪ not supported | +| Web Crypto API | 🟢 supported | +| Web Streams API | 🟢 supported | +| Worker threads | ⚪ not supported | +| [Zlib](/workers/runtime-apis/nodejs/zlib/) | 🟢 supported | + +Unless otherwise specified, native implementations of Node.js APIs in Workers are intended to match the implementation in the [Current release of Node.js](https://github.com/nodejs/release#release-schedule). - - -Unless otherwise specified, implementations of Node.js APIs in Workers are intended to match the implementation in the [Current release of Node.js](https://github.com/nodejs/release#release-schedule). - -## Node.js API Polyfills +If an API you wish to use is missing and you want to suggest that Workers support it, please add a post or comment in the +[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub. -To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your wrangler configuration. This also enables `nodejs_compat_v2` as long as your compatibility date is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). +### Node.js API Polyfills -Adding polyfills maximizes compatibility with existing npm packages, while recognizing that not all APIs from Node.js make sense in the context of serverless functions. +Node.js APIs that are not yet supported in the Workers runtime are polyfilled via [Wrangler](/workers/wrangler/), which uses [unenv](https://github.com/unjs/unenv). If the `nodejs_compat` [compatibility flag](/workers/configuration/compatibility-flags/) is enabled, and your Worker's [compatibility date](/workers/configuration/compatibility-dates/) is 2024-09-23 or later, Wrangler will automatically inject polyfills into your Worker's code. -Where it is possible to provide a fully functional polyfill of the relevant Node.js API, unenv will do so. -In cases where this is not possible, such as the [`fs`](https://nodejs.org/api/fs.html), unenv adds a module with mocked methods. -Calling these mocked methods will either noop or will throw an error with a message like: +Adding polyfills maximizes compatibility with existing npm packages by providing modules with mocked methods. Calling these mocked methods will either noop or will throw an error with a message like: ``` [unenv] is not implemented yet! @@ -54,14 +96,9 @@ Calling these mocked methods will either noop or will throw an error with a mess This allows you to import packages that use these Node.js modules, even if certain methods are not supported. -For a full list of APIs supported, including information on which are mocked, see the [Node.js compatibility matrix](https://workers-nodejs-compat-matrix.pages.dev). - -If an API you wish to use is missing and you want to suggest that Workers support it, please add a post or comment in the -[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub. - ## Enable only AsyncLocalStorage -To enable only the Node.js `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag. +If you need to enable only the Node.js `AsyncLocalStorage` API, you can enable the `nodejs_als` compatibility flag: From 60817aba2e34e0fda6b8900986a74a7c17b853ad Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Mon, 24 Mar 2025 09:57:51 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Yagiz Nizipli --- src/content/docs/workers/runtime-apis/nodejs/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index 626a336f084209..5cad5e58946d09 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -31,7 +31,7 @@ compatibility_date = "2024-09-23" The runtime APIs from Node.js listed below as "🟢 supported" are currently natively supported in the Workers Runtime. -[Deprecated, experimental, and not yet stable APIs from Node.js](https://nodejs.org/docs/latest/api/documentation.html#stability-index) are not included as part of the list below: +[Deprecated or experimental APIs from Node.js](https://nodejs.org/docs/latest/api/documentation.html#stability-index) are not included as part of the list below: | API Name | Natively supported by the Workers Runtime | |--------------------------------------------------------------------------------------|-------------------------------------------| @@ -67,7 +67,7 @@ The runtime APIs from Node.js listed below as "🟢 supported" are currently nat | [String decoder](/workers/runtime-apis/nodejs/string-decoder/) | 🟢 supported | | Test runner | ⚪ not supported | | [Timers](/workers/runtime-apis/nodejs/timers/) | 🟢 supported | -| TLS/SSL | ⚪ not supported | +| TLS/SSL | 🟡 partially supported | | TTY | ⚪ not supported | | UDP/datagram | ⚪ not supported | | [URL](/workers/runtime-apis/nodejs/url/) | 🟢 supported |