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.

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

Merged
merged 8 commits into from
Feb 5, 2025
+20 −5
Merged

Added no_nodejs_compat_v2 to notes #18765

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 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
3e0f514
Update src/content/docs/workers/configuration/compatibility-flags.mdx
ToriLindsay Jan 30, 2025
870a648
Update src/content/docs/workers/runtime-apis/nodejs/index.mdx
ToriLindsay Jan 30, 2025
bd513a2
Update src/content/docs/workers/runtime-apis/nodejs/index.mdx
ToriLindsay Jan 30, 2025
7a6fad6
Merge branch 'production' into tori/pcx17608-add-no-nodejs-v2-flag
ToriLindsay Jan 30, 2025
9d55866
Update src/content/docs/workers/runtime-apis/nodejs/index.mdx
ToriLindsay Jan 30, 2025
23b9542
added render to fix error
ToriLindsay Feb 5, 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
2 changes: 1 addition & 1 deletion 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 @@ -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.
Copy link
Contributor

@GregBrimble GregBrimble Dec 16, 2024

Choose a reason for hiding this comment

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

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.

Copy link
Contributor

@vicb vicb Dec 16, 2024

Choose a reason for hiding this comment

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

to reduce bundle size

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

Copy link
Contributor Author

@ToriLindsay ToriLindsay Dec 18, 2024

Choose a reason for hiding this comment

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

@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

Copy link
Contributor Author

@ToriLindsay ToriLindsay Dec 18, 2024

Choose a reason for hiding this comment

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

(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)

Copy link
Contributor

@vicb vicb Dec 19, 2024

Choose a reason for hiding this comment

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

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?

Copy link
Contributor Author

@ToriLindsay ToriLindsay Jan 7, 2025

Choose a reason for hiding this comment

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

@petebacondarwin @anonrig
Following up on @vicb's question above since it would be very useful to include this information. Thanks!

Copy link
Contributor

@petebacondarwin petebacondarwin Jan 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I think we could avoid mentioning unenv directly. It is more of an implementation detail.
Really what we are saying is something along the lines of:

v2 augments the runtime's Node.js compatibility by bundling additional polyfills and globals into your Worker. You can disable adding the bundled polyfills, and only get the built-in runtime compatibility, by setting nodejs_compat + no_nodejs_compat_v2. Disabling the bundled polyfills can reduce bundle size and avoid injecting some global variables but should only be used if you know what you are doing.

Copy link
Contributor

@vicb vicb Dec 16, 2024

Choose a reason for hiding this comment

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

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

:::

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
2 changes: 1 addition & 1 deletion 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 @@ -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.
Copy link
Contributor

@GregBrimble GregBrimble Dec 16, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

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.

:::

## Built-in Node.js Runtime APIs
Expand Down
Loading