Skip to content

Commit

Permalink
Update docs for nodejs_compat default enable date (#17043)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
2 people authored and maheshwarip committed Dec 2, 2024
1 parent cf0040e commit 02774b0
Showing 1 changed file with 6 additions and 54 deletions.
60 changes: 6 additions & 54 deletions src/content/docs/workers/runtime-apis/nodejs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,43 +18,28 @@ You can view which APIs are supported using the [Node.js compatability matrix](h

## Get Started

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`:

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat_v2" ]
```

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`:
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.

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat" ]
compatibility_date = "2024-09-23"
```

:::note
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`.
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.
:::

## Built-in Node.js Runtime APIs

The following APIs from Node.js are provided directly by the Workers Runtime. They are available when using `nodejs_compat` or `nodejs_compat_v2`:
The following APIs from Node.js are provided directly by the Workers Runtime when either `nodejs_compat` or `nodejs_compat_v2` are enabled:

<DirectoryListing />

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.

```js
// Do this:
import { Buffer } from "node:buffer";

// Do not do this:
import { Buffer } from "buffer";
```

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

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

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.

Expand All @@ -73,43 +58,10 @@ For a full list of APIs supported, including information on which are mocked, se
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 Node.js with Workers

Add the [`nodejs_compat`](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-dates/#nodejs-compatibility-flag) to your `wrangler.toml`:

```toml title="wrangler.toml"
compatibility_flags = [ "nodejs_compat_v2" ]
```

## Enable Node.js in Pages Functions

### Enable Node.js in Pages with Wrangler

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`:

```sh
npx wrangler pages dev [<DIRECTORY>] --compatibility-flags="nodejs_compat"
```

For additional options, refer to the list of [Pages-specific CLI commands](/workers/wrangler/commands/#dev-1).

### Enable Node.js in Pages from the Cloudflare dashboard

To enable Node.js for your Pages Function from the Cloudflare dashboard:

1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com) and select your account.
2. Select **Workers & Pages** and in **Overview**, select your Pages project.
3. Select **Settings** > **Functions** > **Compatibility Flags**.
4. Add the `nodejs_compat_v2` compatibility flag to your Preview and Production deployments.

## Enable only AsyncLocalStorage

To enable the Node.js `AsyncLocalStorage` API only, use the `nodejs_als` compatibility flag.
To enable only the Node.js `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag.

```toml
compatibility_flags = [ "nodejs_als" ]
```

## Related resources

- Write your Worker code in [ES modules syntax](/workers/reference/migrate-to-module-workers/) for an optimized experience.

0 comments on commit 02774b0

Please sign in to comment.