Added no_nodejs_compat_v2 to notes #18765

ToriLindsay · 2024-12-16T15:34:16Z

cloudflare-workers-and-pages · 2024-12-16T15:42:07Z

Deploying cloudflare-docs with Cloudflare Pages

Latest commit:	`718459d`
Status:	✅ Deploy successful!
Preview URL:	https://1ecd2d7f.cloudflare-docs-7ou.pages.dev
Branch Preview URL:	https://tori-pcx17608-add-no-nodejs.cloudflare-docs-7ou.pages.dev

View logs

github-actions · 2024-12-16T15:48:27Z

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/configuration/compatibility-flags/	https://tori-pcx17608-add-no-nodejs.cloudflare-docs-7ou.pages.dev/workers/configuration/compatibility-flags/
https://developers.cloudflare.com/workers/runtime-apis/nodejs/	https://tori-pcx17608-add-no-nodejs.cloudflare-docs-7ou.pages.dev/workers/runtime-apis/nodejs/

GregBrimble

I'd also like to see an actual Compatibility Flag entry for this in the list below. You can create one by creating a file like ./src/content/compatibility-flags/nodejs-compat-v2.md:

---
_build:
  publishResources: false
  render: never
  list: never

name: "Node.js compatibility v2"
sort_date: "2024-09-23"
enable_date: "2024-09-23"
enable_flag: "nodejs_compat_v2"
disable_flag: "no_nodejs_compat_v2"
---

This flag allows you to import Node.js modules without the `node:` prefix and will polyfill additional Node.js modules and globals that are not available with `nodejs_compat` alone.

GregBrimble · 2024-12-16T15:52:36Z

src/content/docs/workers/configuration/compatibility-flags.mdx

@@ -50,7 +50,7 @@ You can opt into improved Node.js compatibility by using `nodejs_compat_v2` inst
 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`.

 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.
+compatibility_date to 2024-09-23 or later. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.


Take it or leave it:

Suggested change

compatibility_date to 2024-09-23 or later. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.

compatibility_date to 2024-09-23 or later. If you want to explicitly disable these improved Node.js compatibility features (for example, to reduce bundle size), you can use the `no_nodejs_compat_v2` flag.

to reduce bundle size

Maybe we should explicitly explain the difference between nodejs_compat and nodejs_compat_v2.

@vicb @GregBrimble
I feel like, ideally, we’d just remove “to reduce bundle size” and then link “improved Node.js compatibility” to a an explanation in this article of the differences/improvements of v2. Could one of you either draft those v2 improvements here or in another PR or just list them for me here and I’ll add it? Thank you!
(But I also saw your other comments and I will make a task to take a more holistic look at improving the nodejs compat info, in general)
cc: @mikenomitch

(For the purposes of people who might want to use the no_nodejs_compat_v2 flag, we should also make any differences clear that could be disadvantages in some situations)

I feel like, ideally, we’d just remove “to reduce bundle size” and then link “improved Node.js compatibility” to a an explanation in this article of the differences/improvements of v2

+1 to remove details in most places where we and mention the compat flags and link to "this article".

(However I think that the text we are commenting on is located in the article).

About the differences:

v2 improves Node compatibility by using unenv. unenv implements some node modules that are not implemented by workerd. We have to bundle those implementations alongside the user code which explain why the bundle siize increases. But workerd is slowly catching up by implementing modules so that the unenv overhead is less and less significant. On top of that we have increased the allowed bundle size. Another reason for which bundle size is becoming less of a concern.

IMO the other differences "the globals Buffer and process are available everywhere" deserve to be describe. The only reason why I have seen no_nodejs_compat_v2 is to disable process update. @petebacondarwin has more details.

@anonrig Are there any other differences backed in nodejs_compat_v2?

GregBrimble · 2024-12-16T15:52:59Z

src/content/docs/workers/runtime-apis/nodejs/index.mdx

@@ -32,7 +32,7 @@ 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.
+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. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.


Take it or leave it:

Suggested change

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. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.

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. If you want to explicitly disable these improved Node.js compatibility features (for example, to reduce bundle size), you can use the `no_nodejs_compat_v2` flag.

vicb · 2024-12-16T17:06:00Z

src/content/docs/workers/configuration/compatibility-flags.mdx

@@ -50,7 +50,7 @@ You can opt into improved Node.js compatibility by using `nodejs_compat_v2` inst
 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`.

 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.
+compatibility_date to 2024-09-23 or later. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.


Do we need to be more explicit and say "both nodejs_compat and no_nodejs_compat_v2"

vicb · 2024-12-16T17:21:11Z

I'd also like to see an actual Compatibility Flag entry for this in the list below. You can create one by creating a file like ./src/content/compatibility-flags/nodejs-compat-v2.md:

---
_build:
  publishResources: false
  render: never
  list: never

name: "Node.js compatibility v2"
sort_date: "2024-09-23"
enable_date: "2024-09-23"
enable_flag: "nodejs_compat_v2"
disable_flag: "no_nodejs_compat_v2"
---

This flag, when used in conjunction with `nodejs_compat`, allows you to import Node.js modules without the `node:` prefix and will polyfill additional Node.js modules and globals that are not available with `nodejs_compat` alone.

A couple comments:

Sounds weird to use 2024-09-23 for nodejs_compat_v2 as it was available before?
"This flag, when used in conjunction with nodejs_compat" you do not need to use nodejs_compat as nodejs_compat_v2 implies nodejs_compat.

vicb · 2024-12-16T17:30:11Z

This code is useful to understand how this works

  nodeJsCompatV2 @50 :Bool
      $compatEnableFlag("nodejs_compat_v2")
      $compatDisableFlag("no_nodejs_compat_v2")
      $impliedByAfterDate(name = "nodeJsCompat", date = "2024-09-23");
  # Implies nodeJSCompat with the following additional modifications:
  # * Node.js Compat built-ins may be imported/required with or without the node: prefix
  # * Node.js Compat the globals Buffer and process are available everywhere

Basically using nodeJsCompat with a date >= 2024-09-23 implies nodeJsCompatV2.

Using ["nodejs_compat", "no_nodejs_compat_v2"] (after 2024-09-23 but also works before) will only enable nodeJsCompat but not nodeJsCompatV2.

(It took me some time to figure out so it might be helpful to some people reading this issue)

GregBrimble · 2024-12-16T17:32:39Z

Sounds weird to use 2024-09-23 for nodejs_compat_v2 as it was available before?

Right, but 2024-09-23 is just the date when it is enabled by default. Would you expect something else here? Are other there any other compat flags which are more in line with whatever you're thinking?

"This flag, when used in conjunction with nodejs_compat" you do not need to use nodejs_compat as nodejs_compat_v2 implies nodejs_compat.

Ah yes, absolutely. Thanks for catching that. Lemme go edit that suggestion to be just "This flag..."

vicb · 2024-12-16T18:10:28Z

when it is enabled by default

It's enable by default ONLY when nodejs_compat is used. I can not really think of a good way to set the date. Buy maybe we can expand the description to be very clear about that.

GregBrimble · 2024-12-16T19:14:00Z

Maybe a "Requires" row in that mini table? What about something like this?

vicb · 2024-12-16T19:24:43Z

Maybe a "Requires" row in that mini table? What about something like this?

I find it misleading as it might sound like v2 requires nodejs_compat.

IMO the only sane way to explain this would be "implied by: nodejs_compat and compatibility_date >= 2024-09-23". Not sure if we need a row, explaining this in description would work.

vicb · 2024-12-17T06:45:26Z

Looking at https://developers.cloudflare.com/workers/configuration/compatibility-flags/, we do not have a en entry for nodejs_compat in https://developers.cloudflare.com/workers/configuration/compatibility-flags/#flags-history.

So maybe we do not need an entry for nodejs_compat_v2 there?

There is an existing https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-compatibility-flag section where we can add details.

GregBrimble · 2024-12-17T15:10:51Z

Yeah, we really should add both here. These listings also power APIs which are used by the dashboard for selecting compat flags/dates.

vicb · 2024-12-17T15:23:47Z

These listings also power APIs which are used by the dashboard for selecting compat flags/dates.

I was thinking about exactly that yesterday (the dashboard list).
I don't see it as a reason to add them to the list.
What I mean is that I would prefer that:

those 2 flags are always added to the list (on the consumer side)
we keep the documentation in this existing separate section because we don't really want them to get lost in the middle of the list and they do not have a "Default as of" either.

Note that this is only thoughts no strong opinions (as long as the docs accurately describe the flags)

GregBrimble · 2024-12-17T15:58:28Z

Yeah, whatever — I don't hugely care either way to be honest. I've said my piece :) PCX/Product can make calls about exactly how they want to describe and expose these. I'm sure it'll be fine either way.

Added no_nodejs_compat_v2 to notes

718459d

ToriLindsay requested review from irvinebroque, jasnell, mikenomitch, GregBrimble, a team and WalshyDev as code owners December 16, 2024 15:34

ToriLindsay mentioned this pull request Dec 16, 2024

Add documentation for no_nodejs_compat_v2 compatibility flag #17608

Open

github-actions bot assigned GregBrimble, irvinebroque, mikenomitch, WalshyDev and jasnell Dec 16, 2024

github-actions bot added size/xs product:workers Related to Workers product labels Dec 16, 2024

GregBrimble requested changes Dec 16, 2024

View reviewed changes

vicb reviewed Dec 16, 2024

View reviewed changes

vicb mentioned this pull request Dec 16, 2024

nodejs_compat(_v2), clarification + factor docs #18773

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added no_nodejs_compat_v2 to notes #18765

Added no_nodejs_compat_v2 to notes #18765

ToriLindsay commented Dec 16, 2024

cloudflare-workers-and-pages bot commented Dec 16, 2024

github-actions bot commented Dec 16, 2024

GregBrimble left a comment •

edited

Loading

GregBrimble Dec 16, 2024

vicb Dec 16, 2024

ToriLindsay Dec 18, 2024

ToriLindsay Dec 18, 2024

vicb Dec 19, 2024

GregBrimble Dec 16, 2024 •

edited

Loading

vicb Dec 16, 2024

vicb commented Dec 16, 2024

vicb commented Dec 16, 2024 •

edited

Loading

GregBrimble commented Dec 16, 2024

vicb commented Dec 16, 2024

GregBrimble commented Dec 16, 2024

vicb commented Dec 16, 2024

vicb commented Dec 17, 2024

GregBrimble commented Dec 17, 2024

vicb commented Dec 17, 2024

GregBrimble commented Dec 17, 2024

	compatibility_date to 2024-09-23 or later. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.
	compatibility_date to 2024-09-23 or later. If you want to explicitly disable these improved Node.js compatibility features (for example, to reduce bundle size), you can use the `no_nodejs_compat_v2` flag.

	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. If you want to explicitly disable the Node.js v2 compatibility features to reduce bundle size, you can use the `no_nodejs_compat_v2` flag.
	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. If you want to explicitly disable these improved Node.js compatibility features (for example, to reduce bundle size), you can use the `no_nodejs_compat_v2` flag.

Added no_nodejs_compat_v2 to notes #18765

Are you sure you want to change the base?

Added no_nodejs_compat_v2 to notes #18765

Conversation

ToriLindsay commented Dec 16, 2024

cloudflare-workers-and-pages bot commented Dec 16, 2024

Deploying cloudflare-docs with Cloudflare Pages

github-actions bot commented Dec 16, 2024

GregBrimble left a comment • edited Loading

Choose a reason for hiding this comment

GregBrimble Dec 16, 2024

Choose a reason for hiding this comment

vicb Dec 16, 2024

Choose a reason for hiding this comment

ToriLindsay Dec 18, 2024

Choose a reason for hiding this comment

ToriLindsay Dec 18, 2024

Choose a reason for hiding this comment

vicb Dec 19, 2024

Choose a reason for hiding this comment

GregBrimble Dec 16, 2024 • edited Loading

Choose a reason for hiding this comment

vicb Dec 16, 2024

Choose a reason for hiding this comment

vicb commented Dec 16, 2024

vicb commented Dec 16, 2024 • edited Loading

GregBrimble commented Dec 16, 2024

vicb commented Dec 16, 2024

GregBrimble commented Dec 16, 2024

vicb commented Dec 16, 2024

vicb commented Dec 17, 2024

GregBrimble commented Dec 17, 2024

vicb commented Dec 17, 2024

GregBrimble commented Dec 17, 2024

GregBrimble left a comment •

edited

Loading

GregBrimble Dec 16, 2024 •

edited

Loading

vicb commented Dec 16, 2024 •

edited

Loading