diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index f76008f881c60df..5a0b477fa9b90d1 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, 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 on or after 2024-09-23 ```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`. +Starting on September 23rd, 2024, when your compatibility date is on or after `2024-09-23`, the `nodejs_compat` compatibility flag enables the exact same behavior as the `nodejs_compat_v2` compatibility flag does. ::: ## 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 on or after `2024-09-23`, 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.