#10002·npm

[DOCS] Clarify whether `os`, `cpu`, and `libc` accept a string or must be an array

Author: lixiaoyanCreated Sep 20, 2026Updated Sep 29, 2026
LabelsPriority 2Documentation

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:

json
{
  "os": ["darwin", "linux"]
}

The cpu section likewise documents an array. But the libc section, a few paragraphs below, documents both fields as plain strings:

json
{
  "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 (same typeof 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" makes yarn install fail with invalid type: string "glibc", expected a sequence and 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) types os and cpu as array of string only, so "os": "linux" is flagged as invalid in editors — and it has no top-level libc property at all, so libc gets 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