Skip to content

Added no_nodejs_compat_v2 to notes #18765

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.

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

Merged
merged 8 commits into from
Feb 5, 2025
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,14 @@ Compatibility flags can be set when uploading a Worker using the [Workers Script

## Node.js compatibility flag

import { Render } from "~/components";
:::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.
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.


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

<Render file="nodejs_compat" product="workers" />

Expand Down
15 changes: 12 additions & 3 deletions src/content/docs/workers/runtime-apis/nodejs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,18 @@ You can view which APIs are supported using the [Node.js compatibility matrix](h

## Get Started

import { Render } from "~/components";
To enable built-in Node.js APIs and add polyfills, you need to add the `nodejs_compat` compatibility flag to your 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).

<Render file="nodejs_compat" product="workers" />
import { WranglerConfig } from "~/components";

<WranglerConfig>

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

</WranglerConfig>

## Built-in Node.js Runtime APIs

Expand All @@ -32,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` compatibility 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 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).

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