doc,esm: add history support info by aduh95 · Pull Request #35395 · nodejs/node · GitHub

Documents which versions of Node.js support which ESM-feature. This is intended to help library authors determine the minimal Node.js version that supports the features they are using.

I've tried to come up with an exhaustive list of ESM-only features that may impact the way one can write modules:

Unflagged ESM
Unflagged TLA
Supports for .js ES modules

Am I missing something?

Refs: #35370 (comment)

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

cc @guybedford

Review requested:

@nodejs/modules

Another important one is "exports", though I think that has its own section with history?

Another important one is "exports", though I think that has its own section with history?

That's correct:

node/doc/api/packages.md

Lines 856 to 875 in 6fc3b0d

    
           ### `"exports"` 
        
           <!-- YAML 
        
           added: v12.7.0 
        
           changes: 
        
             - version: 
        
               - v12.16.0 
        
               - v13.2.0 
        
               pr-url: https://github.com/nodejs/node/pull/29978 
        
               description: Implement conditional exports. 
        
             - version: 
        
               - v12.15.0 
        
               - v13.7.0 
        
               pr-url: https://github.com/nodejs/node/pull/31001 
        
               description: Remove the `--experimental-conditional-exports` option. 
        
             - version: 
        
               - v12.16.0 
        
               - v13.7.0 
        
               pr-url: https://github.com/nodejs/node/pull/31008 
        
               description: Implement logical conditional exports ordering. 
        
           -->

Now that #35249 has landed, I think it makes sense to include it in this table as it certainly impact the way users are going to interact with CJS from ESM. PTAL

If you want this to be such a more comprehensive history of the major milestones, and we are doing REPLACEME's as well, then I would suggest also including these key milestones too:

"imports" field
conditional exports
"exports" patterns
package own name resolution

conditional exports

"exports" patterns

That doesn't impact the way one writes an ES module, this impacts package authors I'd say.

"imports" field

package own name resolution

Not sure about these ones, they are not ESM-specific right? If so, that's probably more for package authors as well.

Let me add a similar support table at the top of packages.md to document support for those features. Would that work for you?

That sounds like a good separation yes. Perhaps we just have "type" mentioned on both as well.

CI: https://ci.nodejs.org/job/node-test-pull-request/33401/ ✅

Documents which versions of Node.js support which ESM-feature. PR-URL: nodejs#35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Landed in a556484

Documents which versions of Node.js support which ESM-feature. PR-URL: #35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Documents which versions of Node.js support which ESM-feature. PR-URL: nodejs#35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Documents which versions of Node.js support which ESM-feature. Backport-PR-URL: #35757 PR-URL: #35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Documents which versions of Node.js support which ESM-feature. PR-URL: nodejs#35395 Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

nodejs-github-bot added doc Issues and PRs related to the documentations. esm Issues and PRs related to the ECMAScript Modules implementation. labels Sep 28, 2020

GeoffreyBooth reviewed Sep 28, 2020

View reviewed changes

Comment thread doc/api/esm.md Outdated

GeoffreyBooth approved these changes Sep 28, 2020

View reviewed changes

guybedford approved these changes Sep 29, 2020

View reviewed changes

aduh95 mentioned this pull request Sep 29, 2020

doc: packages docs feedback #35370

Closed

3 tasks

guybedford reviewed Sep 29, 2020

View reviewed changes

Comment thread doc/api/esm.md Outdated

aduh95 commented Sep 29, 2020

View reviewed changes

Comment thread doc/api/esm.md Outdated

Comment thread doc/api/packages.md Outdated

Trott reviewed Sep 30, 2020

View reviewed changes

Comment thread doc/api/esm.md Outdated

Trott approved these changes Sep 30, 2020

View reviewed changes

aduh95 commented Sep 30, 2020

View reviewed changes

Comment thread doc/api/packages.md Outdated

aduh95 commented Sep 30, 2020

View reviewed changes

Comment thread doc/api/packages.md Outdated

jasnell approved these changes Oct 1, 2020

View reviewed changes

lpinca added the request-ci Add this label to start a Jenkins CI on a PR. label Oct 4, 2020

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. label Oct 4, 2020

This comment has been minimized.

Sign in to view

Trott force-pushed the add-esm-history branch from e26b702 to a556484 Compare October 5, 2020 13:06

Trott merged commit a556484 into nodejs:master Oct 5, 2020

aduh95 deleted the add-esm-history branch October 5, 2020 13:20

danielleadams mentioned this pull request Oct 6, 2020

V14.13.1 proposal #35525

Merged

aduh95 added the backport-open-v12.x label Oct 22, 2020

aduh95 mentioned this pull request Oct 23, 2020

[v12 backport] ESM (named exports for CJS, package.json docs, subpath export patterns, warning removal) #35757

Closed

3 tasks

aduh95 added backported-to-v12.x and removed backport-open-v12.x labels Nov 3, 2020

MylesBorins mentioned this pull request Nov 3, 2020

v12.20.0 proposal #35950

Merged

doc,esm: add history support info by aduh95 · Pull Request #35395 · nodejs/node · GitHub

Uh oh!

Uh oh!

doc,esm: add history support info - #35395

doc,esm: add history support info#35395Trott merged 1 commit intonodejs:masternodejs/node:masterfrom aduh95:add-esm-historyaduh95/node:add-esm-historyCopy head branch name to clipboard

Conversation

aduh95 commented Sep 28, 2020

Checklist

Uh oh!

nodejs-github-bot commented Sep 28, 2020

Uh oh!

Uh oh!

GeoffreyBooth commented Sep 28, 2020

Uh oh!

aduh95 commented Sep 28, 2020

Uh oh!

aduh95 commented Sep 29, 2020

Uh oh!

guybedford left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aduh95 commented Sep 29, 2020

Uh oh!

guybedford commented Sep 29, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

nodejs-github-bot commented Oct 5, 2020 • edited by Trott Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Trott commented Oct 5, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

doc,esm: add history support info#35395
Trott merged 1 commit into
nodejs:masterfrom
aduh95:add-esm-history

nodejs-github-bot commented Oct 5, 2020 •
edited by Trott
Loading