doc: clarify extensionless esm #30657
Conversation
There was a problem hiding this comment.
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
doc/api/esm.md
Outdated
| @@ -92,6 +92,9 @@ if the nearest parent `package.json` contains `"type": "module"`. | |||
| ```js | |||
| // my-app.js, part of the same example as above | |||
| 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 | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Ah I see. Yeah it could definitely be clarified.
There was a problem hiding this comment.
Would you be ok removing this line and instead clarifying above?
There was a problem hiding this comment.
Done. Had trouble writing it succinctly so let me know if it makes sense.
MylesBorins
added
the
esm
What do you mean by "non-standard flag"? |
azz
changed the title
Co-Authored-By: Myles Borins <[email protected]>
Co-Authored-By: Myles Borins <[email protected]>
Co-Authored-By: Myles Borins <[email protected]>
|
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. |
Fixes: #30655 PR-URL: #30657 Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Myles Borins <[email protected]>
|
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) |
Fixes: #30655 PR-URL: #30657 Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Myles Borins <[email protected]>
Fixes: #30655 PR-URL: #30657 Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Myles Borins <[email protected]>
Fixes: #30655 PR-URL: #30657 Reviewed-By: Yorkie Liu <[email protected]> Reviewed-By: Myles Borins <[email protected]>
Fixes #30655
Checklist
make -j4 test(UNIX), orvcbuild test(Windows) passes