doc: update packages documentation for Node.js 12 EOL

[guybedford]

This updates the packages documentation to update some of the modules "exports" guidance with the Node.js 12 EOL, specifically:

• "main" is no longer required as a fallback when using "exports", instead we explain how to decide which to use based on version support. I have gone quite strongly here in recommending the "exports" pattern - this guidance could certainly be relaxed to be more generous to keeping "main" around as well.
• In all "exports" examples, I've shifted to the pattern of including the file extension in the subpath, as has kind of come to be seen as the better approach to ensure interop with import maps. I've mentioned some brief notes around this and updated all the examples, including the patterns examples to use pattern trailers.
• I've updated the version history on subpath patterns to include the history for imports pattern support and pattern trailers support.
• I've moved the exports sugar section higher up, this should help make the linear flow a little easier to understand since we jump between forms.
• Added a new section on extensionless versus extensioned subpaths

/cc @nodejs/modules

[nodejs-github-bot]

Review requested:

• @nodejs/modules

[aduh95]

It looks like make test-doc is failing.

[ljharb]

Suggested change

	"./submodule.js": "./src/submodule.js"
	"./submodule": "./src/submodule.js"

[ljharb]

i still think these examples shouldn't be changed to add the extension.

[aduh95]

I don’t really understand what’s motivating this change either, if anything that adds more bloat to the import maps – I mean it adds 3 bytes; jokes aside, it could give the reader the impression that using an extension is required when defining an export path, and/or confuse needlessly the package consumers on why the is no submodule.js file at the trot of the package – whereas extensionless makes a good job signaling we’re not dealing with actual paths imo.
(Same thing for the change main.js -> index.js, I don’t think it’s necessary)

That being said, I don’t feel strongly about this, so feel free to disregard.

[ljharb]

Suggested change

	import submodule from 'es-module-package/submodule.js';
	import submodule from 'es-module-package/submodule';

[ljharb]

The docs should only reflect node's present, not node's (quite uncertain) future wrt import maps.

When node supports import maps, and the feature is sadly unable to support the most common node ecosystem pattern, then that would be the appropriate time to have opinionated docs - not now, when it's still just wishful thinking from a few collaborators.

[ljharb]

Thanks for the iteration here; I think this does a great job minimizing editorializing in the node docs. LGTM.

[ljharb]

i still think these examples shouldn't be changed to add the extension.

[guybedford]

Added some final clarifications to the extensions guidance and hoping to land this soon.

[aduh95]

I don’t really understand what’s motivating this change either, if anything that adds more bloat to the import maps – I mean it adds 3 bytes; jokes aside, it could give the reader the impression that using an extension is required when defining an export path, and/or confuse needlessly the package consumers on why the is no submodule.js file at the trot of the package – whereas extensionless makes a good job signaling we’re not dealing with actual paths imo.
(Same thing for the change main.js -> index.js, I don’t think it’s necessary)

That being said, I don’t feel strongly about this, so feel free to disregard.

[guybedford]

Landed in 74716ad.

[targos]

This needs a backport PR to land on v16.x-staging. There is a conflict because of the "Subpath folder mappings" section and I'm not sure where to put it.

[guybedford]

Thanks, I've posted a backport in #43809.