doc: clarify required-ness of "name" and "version" in package.json files

[eemeli]

The current content of the Creating a package.json file page indicates that the "name" and "version" fields are always required

A package.json file must contain "name" and "version" fields.

whereas the actual package.json docs page clarifies this with:

If you don't plan to publish your package, the name and version fields are optional.

This minor difference is causing some friction with e.g. Webpack making an assumption based on the former page, resulting in webpack/webpack#13457.

It would be good to get this specified; this PR attempts to do so with (hopefully!) sufficiently simple language.

[ljharb]

I think npm itself actually always requires these fields, whether the package is published or not.

[eemeli]

@ljharb npm requires them in the package's top-level package.json, but does not require them for package.json files that are in its subdirectories. The usage pattern that triggers this is the one documented here: https://nodejs.org/api/packages.html#type

This is useful in particular when a package transpiles TS into JS and provides both CJS and ESM endpoints: microsoft/TypeScript#18442 (comment).

[ljharb]

I agree, but the package being published or not isn't the discriminator - it's required in any package, including a private:true one.

[eemeli]

I'm not completely sure about "name", but "version" is certainly optional when a package.json includes "private": true. I use that often in e.g. documentation, when including such as npm workspaces in a monorepo.

[kenshanta]

Is there a plan to merge/close this PR?

[wraithgar]

I'm gonna close this in the interest of erroring on the side of being less confusing. While version is technically not required for private packages that aren't being installed into another directory, trying to explain that subtle distinction is more confusing that saying they're required.