[DOCS] Clarify whether `os`, `cpu`, and `libc` accept a string or must be an array
Is there an existing issue for this?
- I have searched the existing issues
This is a CLI Docs Enhancement, not another kind of Docs Enhancement.
- This is a CLI Docs Enhancement.
Description of Problem
The package.json docs are internally inconsistent about the type of the os, cpu, and libc fields, and the ecosystem has diverged as a result.
The os section documents an array:
{
"os": ["darwin", "linux"]
}The cpu section likewise documents an array. But the libc section, a few paragraphs below, documents both fields as plain strings:
{
"os": "linux",
"libc": "glibc"
}Nowhere does the page state whether a bare string is a supported shorthand or whether the libc example is simply a mistake.
Because npm silently accepts both, packages in the wild use both, and consumers of the manifest have made incompatible choices:
- npm — accepts string or array.
- pnpm (
@pnpm/package-is-installable) — accepts string or array (sametypeof list === 'string'coercion). - Yarn Berry (
packages/yarnpkg-core/sources/Manifest.ts) — requires an array. A string is silently discarded, so the platform constraint is lost without any warning. - Yarn 6 / zpm — requires an array and now hard-errors: yarnpkg/zpm#210, where
sass-embedded's"libc": "glibc"makesyarn installfail withinvalid type: string "glibc", expected a sequenceand exit code 1. In that thread a user asks, reasonably, why a string isn't supported, citing this very npm docs page as justification for the package author's choice. - SchemaStore (
https://json.schemastore.org/package.json, the schema VS Code uses by default) typesosandcpuasarrayofstringonly, so"os": "linux"is flagged as invalid in editors — and it has no top-levellibcproperty at all, solibcgets no validation or completion whatsoever.
So an author who copies the documented libc example directly gets an editor warning, a silently dropped constraint under Yarn Berry, and a failing install under Yarn 6.
Potential Solution
No response
Docs URL
https://docs.npmjs.com/cli/v12/configuring-npm/package-json#libc
Source: npm/cli