You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Update docs for nodejs_compat default enable date (#17043)
* Update docs for nodejs_compat default enable date
Simplifies docs to direct people to use `nodejs_compat` rather than `nodejs_compat_v2`. Tries to reiterate the need to set your compatibility date multiple times, since this is an important detail to follow that could otherwise be missed.
* Apply suggestions from code review
Co-authored-by: ToriLindsay <[email protected]>
* Update src/content/docs/workers/runtime-apis/nodejs/index.mdx
---------
Co-authored-by: ToriLindsay <[email protected]>
Copy file name to clipboardExpand all lines: src/content/docs/workers/runtime-apis/nodejs/index.mdx
+6-54Lines changed: 6 additions & 54 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,43 +18,28 @@ You can view which APIs are supported using the [Node.js compatability matrix](h
18
18
19
19
## Get Started
20
20
21
-
To enable both built-in runtime APIs and polyfills for your Worker, add the [`nodejs_compat_v2`](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag)[compatibility flag](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml`:
22
-
23
-
```toml title="wrangler.toml"
24
-
compatibility_flags = [ "nodejs_compat_v2" ]
25
-
```
26
-
27
-
To only enable built-in runtime APIs, add the [`nodejs_compat`](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag)[compatibility flag](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml`:
21
+
To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the [`nodejs_compat`](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag)[compatibility flag](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml`, and set your compatibility date to September 23rd, 2024 or later.
28
22
29
23
```toml title="wrangler.toml"
30
24
compatibility_flags = [ "nodejs_compat" ]
25
+
compatibility_date = "2024-09-23"
31
26
```
32
27
33
28
:::note
34
-
Starting on September 23rd, 2024, when your compatibility date is on or after `2024-09-23`, the `nodejs_compat` compatibility flag will enable the exact same behavior as `nodejs_compat_v2`.
29
+
As of September 23rd, 2024, the `nodejs_compat` compatibility flag enables the exact same behavior as the `nodejs_compat_v2` compatibility flag, as long as your compatibility date is set to September 23rd, 2024 or later.
35
30
:::
36
31
37
32
## Built-in Node.js Runtime APIs
38
33
39
-
The following APIs from Node.js are provided directly by the Workers Runtime. They are available when using`nodejs_compat` or `nodejs_compat_v2`:
34
+
The following APIs from Node.js are provided directly by the Workers Runtimewhen either`nodejs_compat` or `nodejs_compat_v2` are enabled:
40
35
41
36
<DirectoryListing />
42
37
43
-
Node.js APIs are available under the `node:` prefix, and this prefix must be used when importing modules, both in your code and the npm packages you depend on.
44
-
45
-
```js
46
-
// Do this:
47
-
import { Buffer } from"node:buffer";
48
-
49
-
// Do not do this:
50
-
import { Buffer } from"buffer";
51
-
```
52
-
53
38
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).
54
39
55
40
## Node.js API Polyfills
56
41
57
-
When using the `nodejs_compat_v2` compatability flag, in addition to enabling Node.js APIs in the Workers Runtime, [Wrangler](/workers/wrangler/) will use [unenv](https://github.com/unjs/unenv) to automatically detect uses of Node.js APIs, and add polyfills where relevant.
42
+
When you enable the `nodejs_compat` compatability flag and set your compatibility date to `2024-09-23` or later, in addition to enabling Node.js APIs in the Workers Runtime, [Wrangler](/workers/wrangler/) will use [unenv](https://github.com/unjs/unenv) to automatically detect uses of Node.js APIs, and add polyfills where relevant.
58
43
59
44
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.
60
45
@@ -73,43 +58,10 @@ For a full list of APIs supported, including information on which are mocked, se
73
58
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
74
59
[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub.
75
60
76
-
## Enable Node.js with Workers
77
-
78
-
Add the [`nodejs_compat`](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag)[compatibility flag](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml`:
79
-
80
-
```toml title="wrangler.toml"
81
-
compatibility_flags = [ "nodejs_compat_v2" ]
82
-
```
83
-
84
-
## Enable Node.js in Pages Functions
85
-
86
-
### Enable Node.js in Pages with Wrangler
87
-
88
-
To enable `nodejs_compat` in local development, pass the [`--compatibility-flags`](/workers/wrangler/commands/#dev-1) argument with the `nodejs_compat` flag to `wrangler pages dev`:
89
-
90
-
```sh
91
-
npx wrangler pages dev [<DIRECTORY>] --compatibility-flags="nodejs_compat"
92
-
```
93
-
94
-
For additional options, refer to the list of [Pages-specific CLI commands](/workers/wrangler/commands/#dev-1).
95
-
96
-
### Enable Node.js in Pages from the Cloudflare dashboard
97
-
98
-
To enable Node.js for your Pages Function from the Cloudflare dashboard:
99
-
100
-
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
101
-
2. Select **Workers & Pages** and in **Overview**, select your Pages project.
0 commit comments