Skip to content

Commit 368596a

Browse files
irvinebroqueanonrig
authored and
RebeccaTamachiro
committed
Enumerate Node.js APIs on main Node.js docs page (#20539)
* Enumerate Node.js APIs on main Node.js docs page 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. * Apply suggestions from code review Co-authored-by: Yagiz Nizipli <[email protected]> --------- Co-authored-by: Yagiz Nizipli <[email protected]>
1 parent 08aa483 commit 368596a

File tree

1 file changed

+61
-24
lines changed
  • src/content/docs/workers/runtime-apis/nodejs

1 file changed

+61
-24
lines changed

‎src/content/docs/workers/runtime-apis/nodejs/index.mdx‎

Lines changed: 61 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,11 @@ When you write a Worker, you may need to import packages from [npm](https://www.
1212
Cloudflare Workers provides a subset of Node.js APIs in two forms:
1313

1414
1. As built-in APIs provided by the Workers Runtime
15-
2. As polyfills that [Wrangler](/workers/wrangler/) adds to your Worker's code
16-
17-
You can view which APIs are supported using the [Node.js compatibility matrix](https://workers-nodejs-compat-matrix.pages.dev).
15+
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.
1816

1917
## Get Started
2018

21-
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).
22-
19+
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).
2320

2421
<WranglerConfig>
2522

@@ -30,38 +27,78 @@ compatibility_date = "2024-09-23"
3027

3128
</WranglerConfig>
3229

33-
## Built-in Node.js Runtime APIs
34-
35-
The following APIs from Node.js are provided directly by the Workers Runtime when either `nodejs_compat` or `nodejs_compat_v2` are enabled:
30+
## Supported Node.js APIs
31+
32+
The runtime APIs from Node.js listed below as "🟢 supported" are currently natively supported in the Workers Runtime.
33+
34+
[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:
35+
36+
| API Name | Natively supported by the Workers Runtime |
37+
|--------------------------------------------------------------------------------------|-------------------------------------------|
38+
| [Assertion testing](/workers/runtime-apis/nodejs/assert/) | 🟢 supported |
39+
| [Asynchronous context tracking](/workers/runtime-apis/nodejs/asynclocalstorage/) | 🟢 supported |
40+
| [Buffer](/workers/runtime-apis/nodejs/buffer/) | 🟢 supported |
41+
| C++ addons | ⚪ not supported |
42+
| C/C++ addons with Node-API | ⚪ not supported |
43+
| C++ embedder API | ⚪ not supported |
44+
| Child processes | ⚪ not supported |
45+
| Cluster | ⚪ not supported |
46+
| Console | 🟢 supported |
47+
| [Crypto](/workers/runtime-apis/nodejs/crypto/) | 🟡 partially supported |
48+
| [Debugger](/workers/observability/dev-tools/) | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) |
49+
| [Diagnostics Channel](/workers/runtime-apis/nodejs/diagnostics-channel/) | 🟢 supported |
50+
| [DNS](/workers/runtime-apis/nodejs/dns/) | 🟢 supported |
51+
| Errors | 🟢 supported |
52+
| Events | 🟢 supported |
53+
| File system | ⚪ not supported |
54+
| Globals | 🟢 supported |
55+
| HTTP | ⚪ not supported |
56+
| HTTP/2 | ⚪ not supported |
57+
| HTTPS | ⚪ not supported |
58+
| Inspector | 🟢 supported via [Chrome Dev Tools integration](/workers/observability/dev-tools/) |
59+
| [Net](/workers/runtime-apis/nodejs/net/) | 🟢 supported |
60+
| OS | ⚪ not supported |
61+
| [Path](/workers/runtime-apis/nodejs/path/) | 🟢 supported |
62+
| Performance hooks | 🟡 partially supported |
63+
| Process | 🟢 supported |
64+
| Query strings | 🟢 supported |
65+
| Readline | ⚪ not supported |
66+
| Stream | 🟢 supported |
67+
| [String decoder](/workers/runtime-apis/nodejs/string-decoder/) | 🟢 supported |
68+
| Test runner | ⚪ not supported |
69+
| [Timers](/workers/runtime-apis/nodejs/timers/) | 🟢 supported |
70+
| TLS/SSL | 🟡 partially supported |
71+
| TTY | ⚪ not supported |
72+
| UDP/datagram | ⚪ not supported |
73+
| [URL](/workers/runtime-apis/nodejs/url/) | 🟢 supported |
74+
| [Utilities](/workers/runtime-apis/nodejs/util/) | 🟢 supported |
75+
| V8 | ⚪ not supported |
76+
| VM | ⚪ not supported |
77+
| Web Crypto API | 🟢 supported |
78+
| Web Streams API | 🟢 supported |
79+
| Worker threads | ⚪ not supported |
80+
| [Zlib](/workers/runtime-apis/nodejs/zlib/) | 🟢 supported |
81+
82+
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).
3683

37-
<DirectoryListing />
38-
39-
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).
40-
41-
## Node.js API Polyfills
84+
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
85+
[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub.
4286

43-
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).
87+
### Node.js API Polyfills
4488

45-
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.
89+
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.
4690

47-
Where it is possible to provide a fully functional polyfill of the relevant Node.js API, unenv will do so.
48-
In cases where this is not possible, such as the [`fs`](https://nodejs.org/api/fs.html), unenv adds a module with mocked methods.
49-
Calling these mocked methods will either noop or will throw an error with a message like:
91+
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:
5092

5193
```
5294
[unenv] <method name> is not implemented yet!
5395
```
5496

5597
This allows you to import packages that use these Node.js modules, even if certain methods are not supported.
5698

57-
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).
58-
59-
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
60-
[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub.
61-
6299
## Enable only AsyncLocalStorage
63100

64-
To enable only the Node.js `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag.
101+
If you need to enable only the Node.js `AsyncLocalStorage` API, you can enable the `nodejs_als` compatibility flag:
65102

66103
<WranglerConfig>
67104

0 commit comments

Comments
 (0)