-
Notifications
You must be signed in to change notification settings - Fork 29.8k
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
doc: fixes ESM/CJS wrapper example #34853
Conversation
Review requested:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
the CJS extension was an intentional choice here; what would be broken without this change? |
This comment has been minimized.
This comment has been minimized.
Removed fast-track label given @ljharb's comment |
@ljharb here, a real world example: #34714 (comment) |
That discusses only removing type module, not changing extensions. |
@MylesBorins make a snippet and I copied it: #34714 (comment) |
I think it's useful to leave the Separately, by using |
Because what the maintainers do is to copy-paste that snippet and since they already have all the codebase that has .js extension, just removes the c letter in both places. Since type is module (and they don't know that leaving it like that makes the js files be interpreted as ESM) they brake the package in Node versions that support type module property (so the newer ones). As I pointed out, the snippet is fine but ESM is still new and developers doesn't know how to deal with it. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is not an improvement. The example was written intentionally, as we want to encourage people to include the "type"
field, even if they also use explicit extensions (as in this example).
@GeoffreyBooth I tend to agree with you. However, I think that in this transition period it is important to be sure that the package maintainers are not going to change their pacakge.json file to: {
"type": "module",
"main": "./index.js",
"exports": {
"import": "./wrapper.mjs",
"require": "./index.js"
}
} Any ideas? We can add a warning note that points out that |
The example doesn't use |
@GeoffreyBooth, the purpose of this snippet example is to make it easy to support ESM in CommonJS code. Its audience is developers that have CJS files all over the place (with In addition to that, I hope that we all agree that the scope of a guide/documentation is to be easily understandable by just looking at the paragraph that you need. We cannot hope that all of the devs that are interested in supporting ESM in "legacy" packages are going to read all of the documentation about ESM in order to learn that they have to put |
It sounds like your concern is that people will copy this example, change the So perhaps what would satisfy that concern would be a sentence below the snippet like:
|
@GeoffreyBooth I think that this might fix this specific problem. I am going to revert the snippet and add the disclaimer at the bottom of it. Is it fine? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You need to change the link to Enabling to be relative to the page (see the other links) but otherwise this is fine.
This PR updates ESM wrapper example to prevent package maintainers to broke packages after copy-pasting.
Ref: #34714
Checklist
make -j4 test
(UNIX), orvcbuild test
(Windows) passes