doc: update to package.exports docs

[MylesBorins]

If package authors don't explicitly include all previously supported
entry points introducing package.exports will be a Semver-Major change.

Add a warning about this behavior and offer two potential solutions
for module authors.

Refs: then/is-promise#20

[ljharb]

LGTM!

[novemberborn]

Spotted some grammatical and syntactical errors, see the suggestions.

[guybedford]

Thanks again @MylesBorins for this important docs PR... I do feel quite strongly about this one so just making my feedback explicit here:

• If users really want it not to be a break we can encourage carefully listing all subpaths be provided explicitly, including the package.json itself. In theory other private subpaths are private APIs so it is the fault of the importer if things don't work out there.
• Otherwise, we should encourage users to make exports a major change if they are in doubt (instead of just adding "./": "./"). Conditional exports makes that break small in still supporting CJS, so that such a small break can be palatable.
• I would really prefer we don't mention "./": "./" at all, but if we really must then it should come after the above, and with its own caveats.

Let me know if I can clarify further / assist with getting this through. If it would help I could commit directly to this PR as well with suggestions for further feedback.

[jkrems]

LGTM although I agree with Guy that it may be nice to de-emphasize ./ or at least call out that it may prevent optimization in tools.

[MylesBorins]

I've accepted the proposed change from @robpalme.

@guybedford are you open to approving this PR based on the current text?

[guybedford]

Thanks @MylesBorins the wording is looking much better, let me know what you think about including an example.

[jaydenseric]

Some general thoughts on best practices…

Only exporting index file entries is not optimal:

• This is a breaking change for projects already using deep imports, whether the paths were documented as part of the "public" API or not.
• Deep imports to specific files can be important for people who care about efficient bundling, or even efficiency without bundling.

It's not maintainable to have a massive list of file exports in the package.json as the exports field would need to be carefully edited whenever a file is added, renamed or removed. Often there’s no feedback the exports are wrong due to an oversight or typo until the package is published and users complain something broke.

It’s best to cherry-pick directories instead of files for export. Only files intended to be public should be in an exported directory. Private files should be in separate directories or else nested in a directory (e.g. named private) that is explicitly blacklisted via the package exports field.

IMO the most reasonable way to deal with the dual package hazard is to publish for each piece of the API a single CJS / .js file with module.exports =. Then have an index.mjs and index.js file that exports them as a collection, with the index files exposed via conditional exports in the package.json exports field.

Despite being a seasoned early experimental-modules adopter and closely watching the final ESM implementation develop I've had to learn so many lessons the hard way; there is a tremendous amount to consider. Having a one-size fits all recommendation for package.json fields (files, main, module, exports) and file structure that is not overly complex would go a long way.

[MylesBorins]

@guybedford I've made some changes and would like another review from you please

[GeoffreyBooth]

This is really good. Great work!

[MylesBorins]

I'll land this in 24 hours unless anyone objects

[MylesBorins]

@guybedford If you would like to add it back please include a suggestion and if no one objects I'll land it. Perhaps linking to documentation about the tooling might help alleviate concerns?

…

On Mon, May 4, 2020 at 3:57 PM Guy Bedford ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In doc/api/esm.md <#33074 (comment)>: > -This is important with regard to `require`, since `require` of ES module files -throws an error in all versions of Node.js. To create a package that works both -in modern Node.js via `import` and `require` and also legacy Node.js versions, -see [the dual CommonJS/ES module packages section][]. +As a last resort, package encapsulation can be disabled entirely by creating an +export for the root of the package `"./": "./"`. This will expose every file in +the package at the cost of disabling encapsulation and the tooling and optimization +benefits that come with it. Since these tooling and optimization benefits don't yet exist All my own tooling very much relies on and uses exports for automatic optimization, including the next version of jspm. And I always opt-out of all of these optimizations when ./: ./ is set. I would have preferred we included this line as when giving advice it is always helpful to explain the reason for the advice. That said I understand there has been a silly amount of back and fourth on this PR so I won't press this. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#33074 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADZYV4I7TLTQMT47DMGOS3RP4MZFANCNFSM4MRC4XPA> .

[guybedford]

Thanks @MylesBorins, I've added the suggestion with some slight rewording. @GeoffreyBooth let me know if that works for you?

[MylesBorins]

made some more changes PTAL

[MylesBorins]

landed in 1ffd182