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.

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: esm: improve dual package hazard docs #30345

Closed
wants to merge 9 commits into from

Conversation

GeoffreyBooth
Copy link
Member

@GeoffreyBooth GeoffreyBooth commented Nov 9, 2019

This updates the ES modules docs regarding hazards related to dual packages per the findings in nodejs/modules#409. Basically, the hazard that we previously thought was isolated to divergent specifiers (e.g. 'pkg' resolving to index.cjs for CommonJS and index.mjs for ESM) happens for all dual packages even if the two entry points are at different specifiers (e.g. 'pkg' and 'pkg/module'). Therefore the section on writing dual packages applies not just to conditional exports but to the ES modules implementation generally.

Follow up to #30051.

cc @guybedford @MylesBorins @nodejs/modules-active-members

Checklist

@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label Nov 9, 2019
doc/api/esm.md Outdated Show resolved Hide resolved
doc/api/esm.md Outdated Show resolved Hide resolved
@guybedford
Copy link
Contributor

What I'm looking for specifically is a note like -

Note: While --experimental-conditional-exports is flagged, publishing a package with this pattern will break when used with require() in modern Node.js, unless the --experimental-conditional-exports flag is used by all package consumers.

@guybedford
Copy link
Contributor

The problem specifically is that the break is not visible in testing, and will only become obvious much further down the line.

@GeoffreyBooth GeoffreyBooth force-pushed the dual-package-docs branch 3 times, most recently from 0ba8715 to 68ab812 Compare November 12, 2019 22:04
doc/api/esm.md Outdated Show resolved Hide resolved
Copy link

@robpalme robpalme left a comment

Choose a reason for hiding this comment

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

Minor wording suggestions.

doc/api/esm.md Outdated Show resolved Hide resolved
doc/api/esm.md Outdated Show resolved Hide resolved
doc/api/esm.md Outdated Show resolved Hide resolved
@guybedford guybedford added the author ready PRs that have at least one approval, no pending requests for changes, and a CI started. label Nov 14, 2019
@nodejs-github-bot
Copy link
Collaborator

@nodejs-github-bot
Copy link
Collaborator

doc/api/esm.md Outdated Show resolved Hide resolved
doc/api/esm.md Outdated Show resolved Hide resolved
GeoffreyBooth and others added 2 commits November 16, 2019 11:50
Co-Authored-By: Vse Mozhet Byt <[email protected]>
Co-Authored-By: Vse Mozhet Byt <[email protected]>
MylesBorins pushed a commit that referenced this pull request Nov 17, 2019
Co-Authored-By: Vse Mozhet Byt <[email protected]>
PR-URL: #30345
Reviewed-By: Guy Bedford <[email protected]>
Reviewed-By: Jan Krems <[email protected]>
@MylesBorins
Copy link
Contributor

landed in d9efc7d

@GeoffreyBooth GeoffreyBooth deleted the dual-package-docs branch November 17, 2019 07:55
MylesBorins pushed a commit that referenced this pull request Nov 17, 2019
Co-Authored-By: Vse Mozhet Byt <[email protected]>
PR-URL: #30345
Reviewed-By: Guy Bedford <[email protected]>
Reviewed-By: Jan Krems <[email protected]>
@BridgeAR BridgeAR mentioned this pull request Nov 19, 2019
MylesBorins pushed a commit that referenced this pull request Jan 12, 2020
Co-Authored-By: Vse Mozhet Byt <[email protected]>
PR-URL: #30345
Reviewed-By: Guy Bedford <[email protected]>
Reviewed-By: Jan Krems <[email protected]>
BethGriggs pushed a commit that referenced this pull request Feb 6, 2020
Co-Authored-By: Vse Mozhet Byt <[email protected]>
PR-URL: #30345
Reviewed-By: Guy Bedford <[email protected]>
Reviewed-By: Jan Krems <[email protected]>
@MylesBorins MylesBorins mentioned this pull request Feb 8, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
author ready PRs that have at least one approval, no pending requests for changes, and a CI started. doc Issues and PRs related to the documentations.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants