documentation
documentation copied to clipboard
npm
[FEATURE] Add more fields to the `package.json` documentation
When creating JS libraries, the package.json documentation on docs.npmjs.com is one of the most helpful resources to me. However it is far from complete, there are many fields that aren't documented there, but they are often needed in order to make a working library. These are for example:
exports– which module should be used when using module requests likeimport "package/sub/path", src: [1], [2]typesandtypesVersions– type declarations for TS, src: [3]module– the main entry point for an ESM project, src: [4], [5], [6]type– ~~whether the main entrypoint is~~ whether all.jsfiles are a CommonJS or ES Module, src: [7]
While these options aren't directly used by the NPM CLI, I think it would be great to include them, since they are a de-facto standard shared by many different systems. Should I make a PR that adds them?
That’s not what the type field means - it solely means “whether .js files are the default, CJS, or ESM”. .mjs files are always ESM and .CJS files are always CJS.
Any documentation should be discouraging use of the type field, IMO.
A good just of these fields are documented in the Node.js docs. Would it maybe make sense to point tho those docs rather than duplicating content?
Any documentation should be discouraging use of the type field, IMO.
I know this is an old comment, but it seems to be contradicting the current Node.js docs:
Package authors should include the "type" field, even in packages where all sources are CommonJS. Being explicit about the type of the package will future-proof the package in case the default type of Node.js ever changes, and it will also make things easier for build tools and loaders to determine how the files in the package should be interpreted.
Is there something special with npm documentation? Because I was thinking that current docs should be updates to include, and if possible, prefer ESM packages.
Any documentation should be discouraging use of the type field, IMO.
this is not the opinion of npm, but rather @ljharb.
Is there something special with npm documentation? Because I was thinking that current docs should be updates to include, and if possible, prefer ESM packages.
Please feel free to open a PR with suggested doc changes, but we are unlikely to land copy that is advocating for a specific module system
We should definitely be linking to the Node.js docs for these. These are not fields that npm parses per se, so they aren't really "npm" docs. Node interprets these and uses them when interacting with modules so it should drive the documentation of them. The fields that we document on the npm website are fields that npm interacts with directly.
I was under the impression that npm stands for Node Package Manager and as such is rather exclusively supportive to Node.js than to any other framework.
I apprehend that npm is a project on its own, but given that Node.js is the main npm client aside from web, shouldn't both documentations aim at the same audience and rather recommend the same strategy in their documentation?
