doc,esm: add history support info #35395

aduh95 · 2020-09-28T11:32:38Z

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

nodejs-github-bot · 2020-09-28T11:32:42Z

Review requested:

@nodejs/modules

doc/api/esm.md

GeoffreyBooth · 2020-09-28T13:46:33Z

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

aduh95 · 2020-09-28T13:56:56Z

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. 
        
           -->

aduh95 · 2020-09-29T08:05:31Z

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

guybedford

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

doc/api/esm.md

aduh95 · 2020-09-29T08:36:09Z

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?

guybedford · 2020-09-29T08:37:45Z

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

doc/api/esm.md

doc/api/packages.md

doc/api/esm.md

doc/api/packages.md

nodejs-github-bot · 2020-10-05T12:42:27Z

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>

Trott · 2020-10-05T13:07:12Z

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

doc/api/esm.md Outdated Show resolved Hide resolved

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

doc/api/esm.md Outdated Show resolved Hide resolved

aduh95 commented Sep 29, 2020

View reviewed changes

doc/api/esm.md Outdated Show resolved Hide resolved

doc/api/packages.md Outdated Show resolved Hide resolved

Trott reviewed Sep 30, 2020

View reviewed changes

doc/api/esm.md Outdated Show resolved Hide resolved

Trott approved these changes Sep 30, 2020

View reviewed changes

aduh95 commented Sep 30, 2020

View reviewed changes

doc/api/packages.md Outdated Show resolved Hide resolved

aduh95 commented Sep 30, 2020

View reviewed changes

doc/api/packages.md Outdated Show resolved Hide resolved

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc,esm: add history support info #35395

doc,esm: add history support info #35395

aduh95 commented Sep 28, 2020

nodejs-github-bot commented Sep 28, 2020

GeoffreyBooth commented Sep 28, 2020

aduh95 commented Sep 28, 2020

aduh95 commented Sep 29, 2020

guybedford left a comment

aduh95 commented Sep 29, 2020

guybedford commented Sep 29, 2020

This comment has been minimized.

nodejs-github-bot commented Oct 5, 2020 •

edited by Trott

Trott commented Oct 5, 2020

doc,esm: add history support info #35395

doc,esm: add history support info #35395

Conversation

aduh95 commented Sep 28, 2020

Checklist

nodejs-github-bot commented Sep 28, 2020

GeoffreyBooth commented Sep 28, 2020

aduh95 commented Sep 28, 2020

aduh95 commented Sep 29, 2020

guybedford left a comment

Choose a reason for hiding this comment

aduh95 commented Sep 29, 2020

guybedford commented Sep 29, 2020

This comment has been minimized.

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

Trott commented Oct 5, 2020

nodejs-github-bot commented Oct 5, 2020 •

edited by Trott