From a8d06323fa069638b61fa7b1147291b211ea8c8c Mon Sep 17 00:00:00 2001 From: Brendan Irvine-Broque Date: Thu, 26 Sep 2024 14:57:18 +0100 Subject: [PATCH] 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 * Update src/content/docs/workers/runtime-apis/nodejs/index.mdx --------- Co-authored-by: ToriLindsay --- .../workers/runtime-apis/nodejs/index.mdx | 60 ++----------------- 1 file changed, 6 insertions(+), 54 deletions(-) diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index f76008f881c60d..9ea2ad704ba538 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -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: -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. @@ -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 [] --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.