Skip to content

Commit a8d0632

Browse files
irvinebroqueToriLindsay
authored andcommitted
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]>
1 parent 038b7d8 commit a8d0632

File tree

1 file changed

+6
-54
lines changed
  • src/content/docs/workers/runtime-apis/nodejs

1 file changed

+6
-54
lines changed

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

Lines changed: 6 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -18,43 +18,28 @@ You can view which APIs are supported using the [Node.js compatability matrix](h
1818

1919
## Get Started
2020

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.
2822

2923
```toml title="wrangler.toml"
3024
compatibility_flags = [ "nodejs_compat" ]
25+
compatibility_date = "2024-09-23"
3126
```
3227

3328
:::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.
3530
:::
3631

3732
## Built-in Node.js Runtime APIs
3833

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 Runtime when either `nodejs_compat` or `nodejs_compat_v2` are enabled:
4035

4136
<DirectoryListing />
4237

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-
5338
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).
5439

5540
## Node.js API Polyfills
5641

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.
5843

5944
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.
6045

@@ -73,43 +58,10 @@ For a full list of APIs supported, including information on which are mocked, se
7358
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
7459
[Node.js APIs discussions category](https://github.com/cloudflare/workerd/discussions/categories/node-js-apis) on GitHub.
7560

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.
102-
3. Select **Settings** > **Functions** > **Compatibility Flags**.
103-
4. Add the `nodejs_compat_v2` compatibility flag to your Preview and Production deployments.
104-
10561
## Enable only AsyncLocalStorage
10662

107-
To enable the Node.js `AsyncLocalStorage` API only, use the `nodejs_als` compatibility flag.
63+
To enable only the Node.js `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag.
10864

10965
```toml
11066
compatibility_flags = [ "nodejs_als" ]
11167
```
112-
113-
## Related resources
114-
115-
- Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

0 commit comments

Comments
 (0)