Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added no_nodejs_compat_v2 to notes #18765

Open
wants to merge 2 commits into
base: production
Choose a base branch
from
Open

Added no_nodejs_compat_v2 to notes #18765

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
718459d
Added no_nodejs_compat_v2 to notes
ToriLindsay Dec 16, 2024
232ad25
Added v2 information
ToriLindsay Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions src/content/docs/workers/configuration/compatibility-flags.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,11 +46,10 @@ Compatibility flags can be set when uploading a Worker using the [Workers Script
## Node.js compatibility flag

:::note
You can opt into improved Node.js compatibility by using `nodejs_compat_v2` instead of `nodejs_compat`. This provides the functionality of `nodejs_compat`, but
additionally you can import Node.js modules without the `node:` prefix and use polyfilled Node.js modules and globals that are not available with `nodejs_compat`.
[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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tiny nit: "by bundling additional polyfills and globals into your Worker"

wrangler does bundle additional polyfills but globals are not actually "bundled" - they are only exposed by workerd when v2 is added. However I think the current wording is ok - adding too many details might bring confusion.


On September 23, 2024, `nodejs_compat` will use the improved Node.js compatibility currently enabled with `nodejs_compat_v2`. This will require updating your
compatibility_date to 2024-09-23 or later.
If your compatibility date is before 2024-09-23 and you want to enable v2, add the `nodejs_compat_v2` in addition to the `nodejs_compat` flag.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor nits: before/after might be confusing (wrt to 09-23 included?)

Suggested change
If your compatibility date is before 2024-09-23 and you want to enable v2, add the `nodejs_compat_v2` in addition to the `nodejs_compat` flag.
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`.
:::

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.toml`:
Expand Down
8 changes: 2 additions & 6 deletions src/content/docs/workers/runtime-apis/nodejs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ 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 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.toml`, and set your compatibility date to September 23rd, 2024 or later.
To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your `wrangler.toml`. 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).

import { WranglerConfig } from "~/components";

Expand All @@ -31,10 +31,6 @@ compatibility_date = "2024-09-23"

</WranglerConfig>

:::note
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 when either `nodejs_compat` or `nodejs_compat_v2` are enabled:
Expand All @@ -45,7 +41,7 @@ Unless otherwise specified, implementations of Node.js APIs in Workers are inten

## Node.js API Polyfills

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.
To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your `wrangler.toml`. 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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe wrangler.toml -> wrangler configuration (support for .json was recently added and is probably becoming the default)


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 Down
Loading