doc: clarify extensionless esm by azz · Pull Request #30657

doc: clarify extensionless esm by azz · Pull Request #30657 · nodejs/node

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

Choose a reason for hiding this comment

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

I don't think we should be documenting using a non-standard flag here in the docs... but we could improve the documentation above to make the difference between extensionless file path (path has no extension) and extensionless specifiers (path has extension, specifier doesn't, node resolves extension) clearer

		import './startup.js'; // Loaded as ES module because of package.json

		// Extensionless. Requires 'node --es-module-specifier-resolution=node'
		import './startup'; // Loaded as ES module because of package.json

Choose a reason for hiding this comment

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

Extensionless files, as documented above, are different from extensionless specifiers (which you are documenting here). Extensionless files mean the file path itself has no extension e.g. /path/to/file, not the specifier e.g. './file' where path is /path/to/file.js.

Choose a reason for hiding this comment

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

Ah I see. Yeah it could definitely be clarified.

Choose a reason for hiding this comment

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

Would you be ok removing this line and instead clarifying above?

Choose a reason for hiding this comment

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

Done. Had trouble writing it succinctly so let me know if it makes sense.

MylesBorins added the esm

Issues and PRs related to the ECMAScript Modules implementation.

label

Nov 27, 2019

I don't think we should be documenting using a non-standard flag here

What do you mean by "non-standard flag"?

@azz it is an experimental flag, not an agreed upon official feature. Not having it labelled experimental was actually an oversight.

I'm actually working on making that clearer in #30678

azz changed the title ~~doc: clarify required flag for extensionless esm~~ doc: clarify extensionless esm

Dec 3, 2019

Choose a reason for hiding this comment

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

Took a quick stab at some slightly different text, unsure if it is better. Happy to see this land with the suggested changes ignore or landed.

azz and others added 2 commits

December 5, 2019 18:03

Co-Authored-By: Myles Borins <myles.borins@gmail.com>

Co-Authored-By: Myles Borins <myles.borins@gmail.com>

Co-Authored-By: Myles Borins <myles.borins@gmail.com>

I don't know if is necessary, but in #30699, CJS module will give suggestions when file extension is not provided, maybe it would be nice in this docs.

MylesBorins pushed a commit that referenced this pull request

Dec 18, 2019

Fixes: #30655

PR-URL: #30657
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>

Landed in 3e5967b

@juanarbol I think documenting #30699 is a great idea, but should likely happen in that PR (so we don't land the docs before the change is landed)

BridgeAR pushed a commit that referenced this pull request

Jan 3, 2020

Fixes: #30655

PR-URL: #30657
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>

MylesBorins pushed a commit that referenced this pull request

Jan 12, 2020

Fixes: #30655

PR-URL: #30657
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>

BethGriggs pushed a commit that referenced this pull request

Feb 6, 2020

Fixes: #30655

PR-URL: #30657
Reviewed-By: Yorkie Liu <yorkiefixer@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>