docs: document package.json's "exports" field

[samualtnorman]

Document package.json's "exports" field.

[ljharb]

ideally an example would include "./package.json", so tools can access the package.json file, and would also show multiple examples including conditions, arrays, etc.

[samualtnorman]

thank you for the feedback, I've now documented conditional exports.
I have also documented fallbacks although I have not yet added examples for fallbacks.
is the thing about conditional exports satisfactory (like the video game)?

[samualtnorman]

sorry about the force push, I started writing in GitHub's editor, copy pasted to vscode to carry on editing there, copy pasted back to GitHub's editor to commit but I apparently failed to paste

[ljharb]

higher than 12

see https://npmjs.com/node-exports-info - there’s actually a pretty complex set of feature support and node version matrix.

[samualtnorman]

do you think it would be better to take out the "higher than 12" comment since the version of NPM these docs are for only supports Node.js ^18.17.0 || >=20.5.0 anyway?

[ljharb]

yes - or maybe, "is supported by modern node.js versions"? also this should link to the node documentation of the field, which might be better than having examples here.

[samualtnorman]

I've added your suggestions, how's this so far?

[samualtnorman]

I have made all requested changes. Is this any closer to being merged?

[wraithgar]

Given how in-depth a true documentation of exports needs to be, I second the idea of linking to Node's documentation on this. Node is what is parsing that field, not npm. main was a very simple spec so documentation was likewise simple. This field, not so simple.

[samualtnorman]

Given how in-depth a true documentation of exports needs to be, I second the idea of linking to Node's documentation on this. Node is what is parsing that field, not npm. main was a very simple spec so documentation was likewise simple. This field, not so simple.

Yup. I agree and have linked to Node.js's official docs on the exports field.

[ericmorand]

Isn't there a problem of responsibility here? If npm doesn't know anything about the exports field and doesn't use it at all, doesn't it mean that Node.js maintainer actually highjacked package.json to host something that only belongs to them, and should not be there?

Why would npm maintainers be responsible for maintaining a documentation about something that they don't own and mantain? And if they do, why this and not all the CLI tools that have been using package.json to host their own custom fields? Where does it stop?

[wraithgar]

npm doesn't "own" package.json, it just is one of the primary consumers of it. There have always been fields that folks add to it that npm never looks at. Oftentimes they are undocumented, but sometimes they are very much official, like main. It's just the reality of how Node.js and npm evolved together.

[wraithgar]

Closing in favor of a much smaller footprint + link in #7783