From 66a977cb4118779b0b56f24a23cfea90107084e0 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Wed, 5 Aug 2026 09:39:17 -0700 Subject: [PATCH 1/3] Update nodejs_compat status --- .../2026-08-04-nodejs-compat-default.mdx | 27 +++++++++++++++++++ .../compatibility-flags/nodejs-compat.mdx | 1 + .../configuration/compatibility-flags.mdx | 6 +++-- .../workers/runtime-apis/nodejs/index.mdx | 4 ++- .../partials/workers/nodejs-compat-howto.mdx | 3 +-- .../partials/workers/nodejs_compat.mdx | 4 ++- worker/index.worker.test.ts | 2 +- 7 files changed, 40 insertions(+), 7 deletions(-) create mode 100644 src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx diff --git a/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx b/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx new file mode 100644 index 00000000000..986795d3451 --- /dev/null +++ b/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx @@ -0,0 +1,27 @@ +--- +title: "nodejs_compat compatibility flag is now enabled by default" +description: Workers with a compatibility date of 2026-08-04 or later have Node.js compatibility enabled by default. +products: + - workers +date: 2026-08-04 +--- + +The `nodejs_compat` compatibility flag is now enabled by default for all Workers +with a [compatibility date](/workers/configuration/compatibility-dates/) of +`2026-08-04` or later. You no longer need to explicitly add `nodejs_compat` to +your `compatibility_flags` array. + +This means all [Node.js built-in APIs](/workers/runtime-apis/nodejs/) supported +by the Workers runtime are available by default, including `node:crypto`, +`node:buffer`, `node:stream`, `node:net`, `node:dns`, `node:fs`, `node:http`, +and more. npm packages that depend on these APIs will work without additional +configuration. + +Existing Workers are not affected. If your Worker already specifies `nodejs_compat` +in `compatibility_flags`, it will continue to work as before. If your Worker uses +an older compatibility date, you can still opt in by adding `nodejs_compat` to +`compatibility_flags` manually. + +To explicitly opt out, add `no_nodejs_compat` to your `compatibility_flags`. + +For more information, refer to the [Node.js compatibility documentation](/workers/runtime-apis/nodejs/). diff --git a/src/content/compatibility-flags/nodejs-compat.mdx b/src/content/compatibility-flags/nodejs-compat.mdx index 3a8de2b7ccf..7185a7795db 100644 --- a/src/content/compatibility-flags/nodejs-compat.mdx +++ b/src/content/compatibility-flags/nodejs-compat.mdx @@ -6,6 +6,7 @@ _build: name: "Node.js compatibility" sort_date: "2023-01-15" +enable_date: "2026-08-04" enable_flag: "nodejs_compat" disable_flag: "no_nodejs_compat" --- diff --git a/src/content/docs/workers/configuration/compatibility-flags.mdx b/src/content/docs/workers/configuration/compatibility-flags.mdx index ec6e856f3b7..f4fa1c20ad6 100644 --- a/src/content/docs/workers/configuration/compatibility-flags.mdx +++ b/src/content/docs/workers/configuration/compatibility-flags.mdx @@ -56,10 +56,12 @@ If your compatibility date is 2024-09-22 or before and you want to enable v2, ad If your compatibility date is after 2024-09-23, but you want to disable v2 to avoid increasing your bundle size, add the `no_nodejs_compat_v2` in addition to the `nodejs_compat flag`. ::: -A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs), with no need to add polyfills to your own code. To enable these APIs in your Worker, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/): +A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs/), with no need to add polyfills to your own code. +As of compatibility date `2026-08-04`, the `nodejs_compat` flag is enabled by default. Workers using an older compatibility date can still opt in by adding `nodejs_compat` to their `compatibility_flags`: + ```jsonc @@ -72,7 +74,7 @@ A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available -As additional Node.js APIs are added, they will be made available under the `nodejs_compat` compatibility flag. Unlike most other compatibility flags, we do not expect the `nodejs_compat` to become active by default at a future date. +To explicitly opt out, add `no_nodejs_compat` to your `compatibility_flags`. The Node.js `AsyncLocalStorage` API is a particularly useful feature for Workers. To enable only the `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag. diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index 5534347ae35..d3ae020ef90 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -20,7 +20,9 @@ Cloudflare Workers provides a subset of Node.js APIs in two forms: ## Get Started -To enable built-in Node.js APIs and add polyfills, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/), and ensure that your Worker's [compatibility date](/workers/configuration/compatibility-dates/) is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). +For compatibility dates of `2026-08-04` or later, Workers enables Node.js compatibility by default. Built-in Node.js APIs and polyfills are available without additional configuration. For more information, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). + +If your compatibility date is earlier, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in, and ensure that your compatibility date is `2024-09-23` or later: diff --git a/src/content/partials/workers/nodejs-compat-howto.mdx b/src/content/partials/workers/nodejs-compat-howto.mdx index 2dee652a3cb..0fa02d9e5da 100644 --- a/src/content/partials/workers/nodejs-compat-howto.mdx +++ b/src/content/partials/workers/nodejs-compat-howto.mdx @@ -5,7 +5,6 @@ :::note -To enable built-in Node.js APIs and polyfills, add the nodejs_compat compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/). This also enables nodejs_compat_v2 as long as your compatibility date is 2024-09-23 or later. [Learn more about the Node.js compatibility flag and v2](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). - +As of compatibility date `2026-08-04`, the `nodejs_compat` flag is enabled by default. If your compatibility date is earlier, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in. This also enables `nodejs_compat_v2` as long as your compatibility date is `2024-09-23` or later. Refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) for details. ::: diff --git a/src/content/partials/workers/nodejs_compat.mdx b/src/content/partials/workers/nodejs_compat.mdx index 7eda35ff4c0..aa3c4a15df7 100644 --- a/src/content/partials/workers/nodejs_compat.mdx +++ b/src/content/partials/workers/nodejs_compat.mdx @@ -4,7 +4,9 @@ import { WranglerConfig } from "~/components"; -To enable both built-in runtime APIs and polyfills for your Worker or Pages project, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your [Wrangler configuration file](/workers/wrangler/configuration/), and set your compatibility date to September 23rd, 2024 or later. This will enable [Node.js compatibility](/workers/runtime-apis/nodejs/) for your Workers project. +As of compatibility date `2026-08-04`, [Node.js compatibility](/workers/runtime-apis/nodejs/) is enabled by default for all Workers and Pages projects. If your compatibility date is `2026-08-04` or later, built-in runtime APIs and polyfills are available without any additional configuration. + +If your compatibility date is before `2026-08-04`, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in: diff --git a/worker/index.worker.test.ts b/worker/index.worker.test.ts index de138510bed..ed757ccca79 100644 --- a/worker/index.worker.test.ts +++ b/worker/index.worker.test.ts @@ -53,7 +53,7 @@ describe("Cloudflare Docs", () => { expect(urlFlag.experimental).toBe(false); expect(nodeJsFlag).toBeDefined(); - expect(nodeJsFlag.enable_date).toBe(null); + expect(nodeJsFlag.enable_date).toBe("2026-08-04"); }); it("pages framework configurations", async () => { From ccbef8315de8d8ad4fdd098fe5af947db744fe7d Mon Sep 17 00:00:00 2001 From: MattieTK Date: Tue, 11 Aug 2026 22:54:43 +0100 Subject: [PATCH 2/3] [Workers] Fix Node.js compatibility default guidance --- .../2026-08-04-nodejs-compat-default.mdx | 42 ++++++++++++++----- .../compatibility-flags/nodejs-compat.mdx | 4 +- .../configuration/compatibility-flags.mdx | 20 +++++---- .../workers/runtime-apis/nodejs/index.mdx | 14 ++++--- .../partials/workers/nodejs-compat-howto.mdx | 2 +- .../partials/workers/nodejs_compat.mdx | 7 ++-- 6 files changed, 61 insertions(+), 28 deletions(-) diff --git a/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx b/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx index 986795d3451..6fb3e406619 100644 --- a/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx +++ b/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx @@ -1,15 +1,17 @@ --- -title: "nodejs_compat compatibility flag is now enabled by default" -description: Workers with a compatibility date of 2026-08-04 or later have Node.js compatibility enabled by default. +title: "Node.js compatibility is now enabled by default" +description: Workers with a compatibility date of 2026-08-04 or later enable Node.js compatibility by default. products: - workers date: 2026-08-04 --- -The `nodejs_compat` compatibility flag is now enabled by default for all Workers -with a [compatibility date](/workers/configuration/compatibility-dates/) of -`2026-08-04` or later. You no longer need to explicitly add `nodejs_compat` to -your `compatibility_flags` array. +import { WranglerConfig } from "~/components"; + +Workers now enable the `nodejs_compat` and `nodejs_compat_v2` compatibility +flags by default for [compatibility dates](/workers/configuration/compatibility-dates/) +of `2026-08-04` or later. Do not add either flag to the `compatibility_flags` +array for these compatibility dates. This means all [Node.js built-in APIs](/workers/runtime-apis/nodejs/) supported by the Workers runtime are available by default, including `node:crypto`, @@ -17,11 +19,29 @@ by the Workers runtime are available by default, including `node:crypto`, and more. npm packages that depend on these APIs will work without additional configuration. -Existing Workers are not affected. If your Worker already specifies `nodejs_compat` -in `compatibility_flags`, it will continue to work as before. If your Worker uses -an older compatibility date, you can still opt in by adding `nodejs_compat` to -`compatibility_flags` manually. +Workers using an earlier compatibility date are not affected. They can still +opt in by adding `nodejs_compat` to `compatibility_flags`. + +When updating an existing Worker to `2026-08-04` or later, remove explicit +`nodejs_compat` and `nodejs_compat_v2` flags. The `workerd` runtime rejects a +redundant `nodejs_compat` flag with the following error: + +```txt output +The compatibility flag nodejs_compat became the default as of 2026-08-04 so does not need to be specified anymore. +``` + +Remove `nodejs_compat` and `nodejs_compat_v2` to resolve the error. Node.js +compatibility remains enabled through the compatibility date. + +To turn off Node.js compatibility completely, add both of the following flags: + + + +```toml +compatibility_date = "$today" +compatibility_flags = ["no_nodejs_compat", "no_nodejs_compat_v2"] +``` -To explicitly opt out, add `no_nodejs_compat` to your `compatibility_flags`. + For more information, refer to the [Node.js compatibility documentation](/workers/runtime-apis/nodejs/). diff --git a/src/content/compatibility-flags/nodejs-compat.mdx b/src/content/compatibility-flags/nodejs-compat.mdx index 7185a7795db..21b7c4e4f7c 100644 --- a/src/content/compatibility-flags/nodejs-compat.mdx +++ b/src/content/compatibility-flags/nodejs-compat.mdx @@ -13,7 +13,7 @@ disable_flag: "no_nodejs_compat" import { Render } from "~/components"; -Enables [Node.js APIs](/workers/runtime-apis/nodejs/) in the Workers Runtime. +Enables [Node.js APIs](/workers/runtime-apis/nodejs/) in the Workers Runtime. For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Note that some Node.js APIs are only enabled when your Worker's compatibility date is on or after the following dates: @@ -32,4 +32,6 @@ The following stubs are enabled automatically only when `nodejs_compat` is enabl When enabling `nodejs_compat`, we recommend using the latest version of [Wrangler CLI](/workers/wrangler/), and the latest compatibility date, in order to maximize compatibility. Some older versions of Wrangler inject additional polyfills that are no longer necessary when your Worker uses a more recent compatibility date, because they are provided by the Workers runtime. +For compatibility dates of `2026-08-04` or later, do not add `nodejs_compat` or `nodejs_compat_v2` explicitly. To turn off Node.js compatibility completely, add both `no_nodejs_compat` and `no_nodejs_compat_v2`. + If you see errors using a particular npm package on Workers, you should first try updating your compatibility date and use the latest version of [Wrangler CLI](/workers/wrangler/) or the [Cloudflare Vite Plugin](/workers/vite-plugin/). If you still encounter issues, please report them by [opening a GitHub issue](https://github.com/cloudflare/workers-sdk/issues/new?template=bug-template.yaml). diff --git a/src/content/docs/workers/configuration/compatibility-flags.mdx b/src/content/docs/workers/configuration/compatibility-flags.mdx index f4fa1c20ad6..f55ee780568 100644 --- a/src/content/docs/workers/configuration/compatibility-flags.mdx +++ b/src/content/docs/workers/configuration/compatibility-flags.mdx @@ -50,32 +50,38 @@ Compatibility flags can be set when uploading a Worker using the [Workers Script ## Node.js compatibility flag :::note -[The `nodejs_compat` flag](/workers/runtime-apis/nodejs/) also enables `nodejs_compat_v2` as long as your compatibility date is 2024-09-23 or later. The v2 flag improves runtime Node.js compatibility by bundling additional polyfills and globals into your Worker. However, this improvement increases bundle size. +[The `nodejs_compat` flag](/workers/runtime-apis/nodejs/) also enables `nodejs_compat_v2` for compatibility dates from `2024-09-23` through `2026-08-03`. The v2 flag improves Node.js compatibility by bundling additional polyfills and globals into your Worker. However, this improvement increases bundle size. -If your compatibility date is 2024-09-22 or before and you want to enable v2, add the `nodejs_compat_v2` in addition to the `nodejs_compat` flag. -If your compatibility date is after 2024-09-23, but you want to disable v2 to avoid increasing your bundle size, add the `no_nodejs_compat_v2` in addition to the `nodejs_compat flag`. +For compatibility dates through `2024-09-22`, add `nodejs_compat_v2` alongside `nodejs_compat` to turn on v2. For compatibility dates from `2024-09-23` through `2026-08-03`, add `no_nodejs_compat_v2` alongside `nodejs_compat` to use v1 only. ::: A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available directly as [Runtime APIs](/workers/runtime-apis/nodejs/), with no need to add polyfills to your own code. -As of compatibility date `2026-08-04`, the `nodejs_compat` flag is enabled by default. Workers using an older compatibility date can still opt in by adding `nodejs_compat` to their `compatibility_flags`: +For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Do not add either flag explicitly. The `workerd` runtime rejects a redundant `nodejs_compat` flag with the following error: + +```txt output +The compatibility flag nodejs_compat became the default as of 2026-08-04 so does not need to be specified anymore. +``` + +Remove `nodejs_compat` and `nodejs_compat_v2` from your configuration to resolve the error. Node.js compatibility remains enabled through the compatibility date. Wrangler, the Cloudflare Vite plugin, and Vitest Pool Workers infer today's date when `compatibility_date` is missing. Therefore, you can encounter this error without updating your configuration. + +To turn off Node.js compatibility completely for a compatibility date of `2026-08-04` or later, add both of the following flags: ```jsonc { "compatibility_flags": [ - "nodejs_compat" + "no_nodejs_compat", + "no_nodejs_compat_v2" ] } ``` -To explicitly opt out, add `no_nodejs_compat` to your `compatibility_flags`. - The Node.js `AsyncLocalStorage` API is a particularly useful feature for Workers. To enable only the `AsyncLocalStorage` API, use the `nodejs_als` compatibility flag. diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index d3ae020ef90..1e8f2d72575 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -20,21 +20,25 @@ Cloudflare Workers provides a subset of Node.js APIs in two forms: ## Get Started -For compatibility dates of `2026-08-04` or later, Workers enables Node.js compatibility by default. Built-in Node.js APIs and polyfills are available without additional configuration. For more information, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). +For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Built-in Node.js APIs and polyfills are available without additional configuration. -If your compatibility date is earlier, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in, and ensure that your compatibility date is `2024-09-23` or later: +Do not add either flag explicitly for these compatibility dates. The `workerd` runtime rejects redundant flags. Remove them from your configuration to resolve the error. Node.js compatibility remains enabled through the compatibility date. + +For compatibility dates from `2024-09-23` through `2026-08-03`, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in: ```jsonc { - "compatibility_flags": ["nodejs_compat"], - "compatibility_date": "$today", + "compatibility_date": "2026-08-03", + "compatibility_flags": ["nodejs_compat"] } ``` +To turn off Node.js compatibility completely with a compatibility date of `2026-08-04` or later, add both `no_nodejs_compat` and `no_nodejs_compat_v2`. For configuration examples, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). + ## Supported Node.js APIs The runtime APIs from Node.js listed in this section with the status "🟢 supported" are currently natively supported in the Workers Runtime. Items listed as "🟡 partially supported" include usable APIs, but do not implement the complete Node.js API surface. @@ -65,7 +69,7 @@ The runtime APIs from Node.js listed in this section with the status "🟢 suppo | [Process](/workers/runtime-apis/nodejs/process/) | 🟢 supported | | [Punycode](https://nodejs.org/docs/latest/api/punycode.html) (deprecated) | 🟢 supported | | [Query strings](https://nodejs.org/docs/latest/api/querystring.html) | 🟢 supported | -| [Stream](/workers/runtime-apis/nodejs/streams/) | 🟢 supported | +| [Stream](/workers/runtime-apis/nodejs/streams/) | 🟢 supported | | [String decoder](/workers/runtime-apis/nodejs/string-decoder/) | 🟢 supported | | [Test runner](/workers/runtime-apis/nodejs/test/) | 🟡 partially supported | | [Timers](/workers/runtime-apis/nodejs/timers/) | 🟢 supported | diff --git a/src/content/partials/workers/nodejs-compat-howto.mdx b/src/content/partials/workers/nodejs-compat-howto.mdx index 0fa02d9e5da..725b40f0689 100644 --- a/src/content/partials/workers/nodejs-compat-howto.mdx +++ b/src/content/partials/workers/nodejs-compat-howto.mdx @@ -5,6 +5,6 @@ :::note -As of compatibility date `2026-08-04`, the `nodejs_compat` flag is enabled by default. If your compatibility date is earlier, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in. This also enables `nodejs_compat_v2` as long as your compatibility date is `2024-09-23` or later. Refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) for details. +For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Do not add either flag explicitly because the `workerd` runtime rejects redundant flags. For earlier dates, add `nodejs_compat` to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in. For instructions to turn off Node.js compatibility or resolve errors, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). ::: diff --git a/src/content/partials/workers/nodejs_compat.mdx b/src/content/partials/workers/nodejs_compat.mdx index aa3c4a15df7..7164e9c4cb3 100644 --- a/src/content/partials/workers/nodejs_compat.mdx +++ b/src/content/partials/workers/nodejs_compat.mdx @@ -4,7 +4,7 @@ import { WranglerConfig } from "~/components"; -As of compatibility date `2026-08-04`, [Node.js compatibility](/workers/runtime-apis/nodejs/) is enabled by default for all Workers and Pages projects. If your compatibility date is `2026-08-04` or later, built-in runtime APIs and polyfills are available without any additional configuration. +For compatibility dates of `2026-08-04` or later, Workers and Pages projects enable both `nodejs_compat` and `nodejs_compat_v2` by default. Built-in runtime APIs and polyfills are available without additional configuration. Do not add either flag explicitly because the `workerd` runtime rejects redundant flags. If your compatibility date is before `2026-08-04`, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in: @@ -14,9 +14,10 @@ If your compatibility date is before `2026-08-04`, add the [`nodejs_compat`](/wo { "compatibility_flags": [ "nodejs_compat" - ], - "compatibility_date": "$today" + ] } ``` + +To turn off [Node.js compatibility](/workers/runtime-apis/nodejs/) completely for a compatibility date of `2026-08-04` or later, add both `no_nodejs_compat` and `no_nodejs_compat_v2`. For configuration examples, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). From 2f0374dab308259886ba1d1eb2604f1351267057 Mon Sep 17 00:00:00 2001 From: MattieTK Date: Wed, 12 Aug 2026 13:43:43 +0100 Subject: [PATCH 3/3] [Workers] Update redundant Node.js flag guidance --- .../2026-08-04-nodejs-compat-default.mdx | 21 +++++++------------ .../compatibility-flags/nodejs-compat.mdx | 2 +- .../configuration/compatibility-flags.mdx | 10 ++------- .../workers/runtime-apis/nodejs/index.mdx | 4 ++-- .../partials/workers/nodejs-compat-howto.mdx | 3 +-- .../partials/workers/nodejs_compat.mdx | 4 ++-- 6 files changed, 16 insertions(+), 28 deletions(-) diff --git a/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx b/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx index 6fb3e406619..60786187e2a 100644 --- a/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx +++ b/src/content/changelog/workers/2026-08-04-nodejs-compat-default.mdx @@ -10,8 +10,8 @@ import { WranglerConfig } from "~/components"; Workers now enable the `nodejs_compat` and `nodejs_compat_v2` compatibility flags by default for [compatibility dates](/workers/configuration/compatibility-dates/) -of `2026-08-04` or later. Do not add either flag to the `compatibility_flags` -array for these compatibility dates. +of `2026-08-04` or later. These flags are not used for these compatibility +dates because the compatibility date enables the same behavior. This means all [Node.js built-in APIs](/workers/runtime-apis/nodejs/) supported by the Workers runtime are available by default, including `node:crypto`, @@ -22,18 +22,13 @@ configuration. Workers using an earlier compatibility date are not affected. They can still opt in by adding `nodejs_compat` to `compatibility_flags`. -When updating an existing Worker to `2026-08-04` or later, remove explicit -`nodejs_compat` and `nodejs_compat_v2` flags. The `workerd` runtime rejects a -redundant `nodejs_compat` flag with the following error: +New projects do not need to add either flag. Existing projects can update their +compatibility date without removing them. Wrangler, Miniflare, the Cloudflare +Vite plugin, and Vitest Pool Workers ignore these redundant flags when starting +the runtime. -```txt output -The compatibility flag nodejs_compat became the default as of 2026-08-04 so does not need to be specified anymore. -``` - -Remove `nodejs_compat` and `nodejs_compat_v2` to resolve the error. Node.js -compatibility remains enabled through the compatibility date. - -To turn off Node.js compatibility completely, add both of the following flags: +To turn off Node.js compatibility completely, remove any `nodejs_compat` and +`nodejs_compat_v2` flags. Then add both of the following flags: diff --git a/src/content/compatibility-flags/nodejs-compat.mdx b/src/content/compatibility-flags/nodejs-compat.mdx index 21b7c4e4f7c..f079898a78f 100644 --- a/src/content/compatibility-flags/nodejs-compat.mdx +++ b/src/content/compatibility-flags/nodejs-compat.mdx @@ -32,6 +32,6 @@ The following stubs are enabled automatically only when `nodejs_compat` is enabl When enabling `nodejs_compat`, we recommend using the latest version of [Wrangler CLI](/workers/wrangler/), and the latest compatibility date, in order to maximize compatibility. Some older versions of Wrangler inject additional polyfills that are no longer necessary when your Worker uses a more recent compatibility date, because they are provided by the Workers runtime. -For compatibility dates of `2026-08-04` or later, do not add `nodejs_compat` or `nodejs_compat_v2` explicitly. To turn off Node.js compatibility completely, add both `no_nodejs_compat` and `no_nodejs_compat_v2`. +For compatibility dates of `2026-08-04` or later, `nodejs_compat` and `nodejs_compat_v2` are not used because the compatibility date enables the same behavior. Existing projects do not need to remove these flags when updating their compatibility date. To turn off Node.js compatibility completely, remove the positive flags if present. Then add both `no_nodejs_compat` and `no_nodejs_compat_v2`. If you see errors using a particular npm package on Workers, you should first try updating your compatibility date and use the latest version of [Wrangler CLI](/workers/wrangler/) or the [Cloudflare Vite Plugin](/workers/vite-plugin/). If you still encounter issues, please report them by [opening a GitHub issue](https://github.com/cloudflare/workers-sdk/issues/new?template=bug-template.yaml). diff --git a/src/content/docs/workers/configuration/compatibility-flags.mdx b/src/content/docs/workers/configuration/compatibility-flags.mdx index f55ee780568..3c5e5da15da 100644 --- a/src/content/docs/workers/configuration/compatibility-flags.mdx +++ b/src/content/docs/workers/configuration/compatibility-flags.mdx @@ -59,15 +59,9 @@ A [growing subset](/workers/runtime-apis/nodejs/) of Node.js APIs are available -For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Do not add either flag explicitly. The `workerd` runtime rejects a redundant `nodejs_compat` flag with the following error: +For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. These flags are not used for these compatibility dates because the compatibility date enables the same behavior. Wrangler, Miniflare, the Cloudflare Vite plugin, and Vitest Pool Workers ignore these redundant flags when starting the runtime. Existing projects do not need to remove them when updating their compatibility date. Omit them from new configurations. -```txt output -The compatibility flag nodejs_compat became the default as of 2026-08-04 so does not need to be specified anymore. -``` - -Remove `nodejs_compat` and `nodejs_compat_v2` from your configuration to resolve the error. Node.js compatibility remains enabled through the compatibility date. Wrangler, the Cloudflare Vite plugin, and Vitest Pool Workers infer today's date when `compatibility_date` is missing. Therefore, you can encounter this error without updating your configuration. - -To turn off Node.js compatibility completely for a compatibility date of `2026-08-04` or later, add both of the following flags: +To turn off Node.js compatibility completely for a compatibility date of `2026-08-04` or later, remove `nodejs_compat` and `nodejs_compat_v2` if present. Then add both of the following flags: diff --git a/src/content/docs/workers/runtime-apis/nodejs/index.mdx b/src/content/docs/workers/runtime-apis/nodejs/index.mdx index 1e8f2d72575..1da0bc948b1 100644 --- a/src/content/docs/workers/runtime-apis/nodejs/index.mdx +++ b/src/content/docs/workers/runtime-apis/nodejs/index.mdx @@ -22,7 +22,7 @@ Cloudflare Workers provides a subset of Node.js APIs in two forms: For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Built-in Node.js APIs and polyfills are available without additional configuration. -Do not add either flag explicitly for these compatibility dates. The `workerd` runtime rejects redundant flags. Remove them from your configuration to resolve the error. Node.js compatibility remains enabled through the compatibility date. +For these compatibility dates, `nodejs_compat` and `nodejs_compat_v2` are not used because the compatibility date enables the same behavior. Existing projects do not need to remove these flags when updating their compatibility date. Omit them from new configurations. For compatibility dates from `2024-09-23` through `2026-08-03`, add the `nodejs_compat` compatibility flag to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in: @@ -37,7 +37,7 @@ For compatibility dates from `2024-09-23` through `2026-08-03`, add the `nodejs_ -To turn off Node.js compatibility completely with a compatibility date of `2026-08-04` or later, add both `no_nodejs_compat` and `no_nodejs_compat_v2`. For configuration examples, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). +To turn off Node.js compatibility completely with a compatibility date of `2026-08-04` or later, remove the positive flags if present. Then add both `no_nodejs_compat` and `no_nodejs_compat_v2`. For configuration examples, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). ## Supported Node.js APIs diff --git a/src/content/partials/workers/nodejs-compat-howto.mdx b/src/content/partials/workers/nodejs-compat-howto.mdx index 725b40f0689..5a130fd103a 100644 --- a/src/content/partials/workers/nodejs-compat-howto.mdx +++ b/src/content/partials/workers/nodejs-compat-howto.mdx @@ -1,10 +1,9 @@ --- {} - --- :::note -For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. Do not add either flag explicitly because the `workerd` runtime rejects redundant flags. For earlier dates, add `nodejs_compat` to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in. For instructions to turn off Node.js compatibility or resolve errors, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). +For compatibility dates of `2026-08-04` or later, Workers enables both `nodejs_compat` and `nodejs_compat_v2` by default. These flags are not used for these compatibility dates. Existing projects do not need to remove them when updating their compatibility date. For earlier dates, add `nodejs_compat` to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in. For instructions to turn off Node.js compatibility, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). ::: diff --git a/src/content/partials/workers/nodejs_compat.mdx b/src/content/partials/workers/nodejs_compat.mdx index 7164e9c4cb3..9cc47e0c5c5 100644 --- a/src/content/partials/workers/nodejs_compat.mdx +++ b/src/content/partials/workers/nodejs_compat.mdx @@ -4,7 +4,7 @@ import { WranglerConfig } from "~/components"; -For compatibility dates of `2026-08-04` or later, Workers and Pages projects enable both `nodejs_compat` and `nodejs_compat_v2` by default. Built-in runtime APIs and polyfills are available without additional configuration. Do not add either flag explicitly because the `workerd` runtime rejects redundant flags. +For compatibility dates of `2026-08-04` or later, Workers and Pages projects enable both `nodejs_compat` and `nodejs_compat_v2` by default. Built-in runtime APIs and polyfills are available without additional configuration. These flags are not used for these compatibility dates. Existing projects do not need to remove them when updating their compatibility date. If your compatibility date is before `2026-08-04`, add the [`nodejs_compat`](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) [compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) to your [Wrangler configuration file](/workers/wrangler/configuration/) to opt in: @@ -20,4 +20,4 @@ If your compatibility date is before `2026-08-04`, add the [`nodejs_compat`](/wo -To turn off [Node.js compatibility](/workers/runtime-apis/nodejs/) completely for a compatibility date of `2026-08-04` or later, add both `no_nodejs_compat` and `no_nodejs_compat_v2`. For configuration examples, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag). +To turn off [Node.js compatibility](/workers/runtime-apis/nodejs/) completely for a compatibility date of `2026-08-04` or later, remove the positive flags if present. Then add both `no_nodejs_compat` and `no_nodejs_compat_v2`. For configuration examples, refer to the [Node.js compatibility flag](/workers/configuration/compatibility-flags/#nodejs-compatibility-flag).