Docs, of the implementation as it is right this moment

[GeoffreyBooth]

This PR updates the docs for where the implementation is currently. The idea is to reflect it as it is, not as it’s eventually going to be; when the expected future changes land, the docs should be updated accordingly. The old --experimental-modules docs are here.

Readable versions:

• https://github.com/nodejs/ecmascript-modules/blob/docs/doc/api/esm.md
• https://github.com/nodejs/ecmascript-modules/blob/docs/doc/api/cli.md

[GeoffreyBooth]

I’ve made some updates per today’s call. Still to do:

• Section very briefly introducing import and export, linking to MDN; @evanplaice will write
• Section listing differences between ESM in Node vs browsers
• Update Specifiers section with info about Windows specifiers; @jdalton do you mind tackling?

In separate PRs:

• Blog post announcing new --experimental-modules (I guess this should be a PR against the modules repo)
• Text explaining migration from old --experimental-modules to new (another blog post?); Documentation: Migrating from --𝚎𝚡𝚙𝚎𝚛𝚒𝚖𝚎𝚗𝚝𝚊𝚕-𝚖𝚘𝚍𝚞𝚕𝚎𝚜 — Discrepancies and Considerations #16

[GeoffreyBooth]

I’m working on a different PR that will need its own docs, which means it needs to build off of this one. So I’d rather merge this in as is and continue to improve it in follow up PRs. The to-do items in my last comment still apply.

Any notes about what’s in this PR?

[MylesBorins]

@GeoffreyBooth reviewing rn

[MylesBorins]

Gotta run to my next meeting so I only had a chance to review half of this. Feel free to land and iterate.

Would like to have guy review the spec changes though

[MylesBorins]

Suggested change

until the root of the volume is reached.

[MylesBorins]

I found the copy here a bit confusing... I'm also struggling to come up with something better.

A package scope is defined as all children of a folder with a package.json that do not themselves have an additional package.json

I think the above is equally confusing though sigh...

[GeoffreyBooth]

It’s not just “all children,” it’s also the folder that the package.json itself is in.

[MylesBorins]

it might be good to have a quick ascii diagram of the filesystem

[GeoffreyBooth]

Like this? https://github.com/GeoffreyBooth/node-import-file-specifier-resolution-proposal/#example

cc @SMotaal

[GeoffreyBooth]

Merging to unblock other PRs, but that doesn’t mean I’m rejecting the above comments; they’ll just need to be addressed in follow-on PRs. Expanded to-do list:

• Section very briefly introducing import and export, linking to MDN; @evanplaice will write
• Section listing differences between ESM in Node vs browsers
• Update Specifiers section with info about Windows specifiers; @jdalton do you mind tackling?
• Add ASCII diagram like this to illustrate package scope and resolution stuff; @SMotaal ?

Maybe:

• Clearer language explaining the search for package.json.
• Clearer language defining “package scope.”

In separate PRs:

• Blog post announcing new --experimental-modules (I guess this should be a PR against the modules repo)
• Text explaining migration from old --experimental-modules to new (another blog post?); Documentation: Migrating from --𝚎𝚡𝚙𝚎𝚛𝚒𝚖𝚎𝚗𝚝𝚊𝚕-𝚖𝚘𝚍𝚞𝚕𝚎𝚜 — Discrepancies and Considerations #16

[guybedford]

This isn't quite true - because we check the extension and throw on conflicts when using "type", while when there is no type there are no conflict errors.

[GeoffreyBooth]

We only throw on conflicts for initial entry points. I was referring to import statements of files within scopes here, though I acknowledge that I didn’t make that explicit 😄.

Do we need to document the cases for which we error?

[GeoffreyBooth]

I rewrote the flags sections as part of https://github.com/nodejs/ecmascript-modules/blob/525e8c9b5d0acc7b8b7895f7ea65b592fdf3e2bd/doc/api/cli.md#--typetype--m--a