Extension · Build Variants

One version, every target.

Build Variants encodes deployment-target coordinates (os, arch, abi and features) as build metadata, so a single release addresses a whole family of artifacts. Because Semantic Versions restores build precedence, each variant is a real, orderable version, and a build channel can select a coherent subset that no numeric range can express.

variant specifier
napi:sharp@0.33.0+linux.x64.musl

napi:sharp@0.33.0 is the release. +linux.x64.musl is the target, an os·arch·abi coordinate, ordered coarse→fine so ranges can drill down.

Why build metadata

A target isn't a pre-release, or a new package.

A platform build is a finished sibling of a release, not a step toward it, so it ranks above the plain release, never below it like a pre-release. And it needn't fork the identity: instead of scattering software across pkg-linux-x64, pkg-darwin-arm64, … wired together with optionalDependencies and os/cpu/libc filters, Build Variants keeps one name, one version, and moves target selection back into the range grammar.

Live

Range over a variant subset.

Every cell is a concrete artifact: a release built for one target. Type a build channel and watch the selected subset light up. Shorter channels are broader subsets; the plain release column has no build, so a channel excludes it. This runs entirely in your browser on the reference semantic-versions parser.

Coordinates

A Build Variant is build metadata whose identifiers name target axes, ordered coarse→fine:

<version>+<os>[.<arch>[.<abi>[.<floor>]]][.<qualifier>]*
<version>+wasm32[.<qualifier>]*
  • The fixed axes appear in order (os, then arch, then abi) and each MAY be omitted only if every later fixed axis is too. A variant is therefore always a prefix of the axis sequence: linux, linux.x64, linux.x64.musl are valid; x64 alone (arch without os) is not. An omitted axis is no constraint: linux.x64 with no abi runs on glibc and musl alike.
  • An abi of glibc or musl MAY carry a version floor, the lowest version of that C library the build runs on: linux.x64.glibc.2.28 runs on glibc 2.28 or later (the manylinux rule).
  • Qualifiers follow the fixed axes, in any order: floors (osv.11.0 for the OS version on darwin and win32, napi.8 for the N-API version an addon needs), exact tags (node.127, electron.123: the NODE_MODULE_VERSION an addon was built against; a variant carries napi or one of these, not both), and feature tags (avx2, cuda, neon), which SHOULD be sorted for a canonical form.
  • wasm32 stands alone as the whole platform: a WebAssembly build is not tied to an operating system.
  • Each value is its own dot-separated build identifier, so a variant slots straight into the existing <build> grammar, and floors are numeric identifiers that compare numerically under the core precedence rules with nothing added.

Registered vocabularies (extensible; aligned with runtime values like Node's process.platform / process.arch, and with the platform fields of pnpm and npm's variants proposal):

Axis or keyValues
oslinux · darwin · win32 · freebsd · openbsd · android · sunos · aix
archx64 · arm64 · arm (ARMv7) · ia32 · ppc64 · s390x · riscv64 · loong64
abiglibc[.M.m] · musl[.M.m] · msvc
platformwasm32, in place of the fixed axes
floorsosv.M[.m] · napi.N
exact tagsnode.N · electron.N
featuresany other lowercase identifier

Consumers MUST ignore axis, key or feature identifiers they don't recognise and MUST NOT treat that as a match failure on its own; an unknown coordinate simply doesn't narrow selection.

Selection

Selection is just the core Build Channels rule applied to coordinates: a +-channel is orthogonal to the numeric comparison and admits only versions whose build coordinates begin with the channel's. Because coordinates are ordered coarse→fine, a shorter channel is a broader subset.

  • ^1.0.0+linux: every linux variant in the 1.x line.
  • ^1.0.0+linux.x64: narrows to linux/x64, both glibc and musl.
  • ^1.0.0+linux.x64.musl: just the musl build.
  • >=1.1.0+darwin.arm64: the Apple-silicon build at or above 1.1.0.
  • 1.2.0+win32.x64: one exact artifact.
  • ^1.0.0: no channel, so every variant and the plain release.

A channel narrows a range to the variants a specifier asks for. Members of a subset still order by precedence, so “the latest linux/x64 build of 1.x” is well-defined: the highest release, and within it the highest build. Precedence among siblings of one release is lexical, though, and says nothing about which sibling suits a machine. That is the job of target matching, below.

Prefix matching means a coarse channel also admits deeper refinements: +linux.x64 matches linux.x64.musl. To distinguish siblings that share a prefix, make the distinguishing axis explicit: model libc as linux.x64.glibc vs linux.x64.musl rather than leaving glibc implicit.

Target matching

A target is what a client installs for: by default the host, described in the same vocabulary as a coordinate (process.platform, process.arch, the C library and its version, the OS version, the N-API version and NODE_MODULE_VERSION, and whatever features the client can detect). A target can also be configured, for a container image or a cross-compile; any value it does not state is unknown.

A variant applies to a target when every coordinate it states is satisfied:

  1. Each fixed axis it states equals the target's. An omitted axis is no constraint. wasm32 applies to every target.
  2. Each floor it states (a C-library version, osv, napi) is at or below the target's value for that key, compared numerically. A floor on a key the target leaves unknown is not satisfied: linking a build the host may not run is worse than falling through to a broader variant.
  3. Each exact tag it states (node, electron) equals the target's.
  4. Each feature tag the client recognises is one the target has; a feature tag the client does not recognise is ignored.

The build-less release applies to every target, as the fallback.

To resolve a range for a target, a client takes the highest release in the range that has at least one applicable member, then the most specific applicable member of that release:

  1. a variant that states more fixed axes before one that states fewer;
  2. then a higher floor before a lower one, and any floor before none;
  3. then an exact node/electron tag before a napi floor before neither;
  4. then a variant that states more matched feature tags;
  5. then a native variant (one with an os) before wasm32, and wasm32 before the build-less release.

So for a glibc 2.31 host with N-API 9, 1.4.0+linux.x64.glibc.2.28.napi.8 wins over 1.4.0+linux.x64.glibc.2.17.napi.8, which wins over 1.4.0+linux.x64, which wins over 1.4.0+wasm32 and 1.4.0. Specificity is computed from the coordinates, so a publisher never has to order anything by hand, and two clients given the same target select the same artifact.

Relationship to other schemes

  • npm os/cpu/libc + optional-dependency fanout. The same target matrix, expressed in one version instead of across many packages, and now rangeable. A resolver can still map a selected variant onto whatever artifact layout a registry uses.
  • pnpm's platform variants. pnpm describes a platform build with os, cpu, libc, libcVersion, osVersion, napi and nodeAbi, ranks the archives of one version by how specific their platform is, and writes the result into its lockfile. That is the same vocabulary as the coordinates above, and the specificity order in target matching is pnpm's rank computed from the coordinate. Build Variants differs in putting the coordinate in the version, where it survives outside a lockfile.
  • npm's variants field (npm/rfcs#928). The RFC lists, on a package, the separate packages that replace it per target, using pnpm's fields; it is the projection of this extension onto registries that hold one artifact per version, and the RFC itself names several archives per version as its future shape. An entry maps onto a coordinate and back:
    variants entryCoordinate
    os, cpu, libc (one value each)the fixed axes, in order
    libcVersion: "2.28"glibc.2.28 on the abi axis (the RFC's floor implies glibc)
    osVersion: "11.0"osv.11.0
    napi: 8napi.8
    nodeAbi: "node-127" / "electron-123"node.127 / electron.123
    an omitted libcan omitted abi
    a cross product (os: ["darwin"], cpu: ["arm64", "x64"])one coordinate per cell, or the common prefix (darwin) when one artifact serves them all
    a !value exclusionno counterpart: a coordinate says what an artifact is, so an exclusion becomes an omitted axis or several coordinates
    engines.nodeno counterpart: a requirement on the consumer, which stays a manifest field
    the unconditional fallback entrywasm32, or the build-less release
    The RFC's author order (“narrower first, higher floors first, nodeAbi before napi, native before the fallback”) is the specificity order here, so a tool can generate a correctly ordered variants list from a set of coordinates.
  • OCI / Docker multi-arch manifests. A manifest list selects by os/architecture/variant; Build Variants lifts that tuple into the version grammar, so the same selection works in a specifier or lockfile, not only at pull time.
  • Package-URL qualifiers. PURL carries target facts in ?arch=…&os=… qualifiers, outside the version and outside precedence. Build Variants keeps them in the version, where they order and where ranges select them, while staying round-trippable to PURL qualifiers for interchange.

Composability

Variant coordinates are ordinary build identifiers, so they compose with other build-metadata extensions. Build Variants is the first of the three extensions for a reason: it answers which artifact, and the other two build on that answer. A variant precedes an integrity digest — 1.0.0+linux.x64.musl.sha512.… pins the exact bytes of one target — and a Dependency Lock pins a whole graph whose every node is an identity of exactly that shape. See Package Integrity for the digest half.

Grammar (BNF)

Building on VERSION.bnf's <build>:

<variant build> ::= <platform> ( "." <qualifier> )*
<platform>      ::= <os> ( "." <arch> ( "." <abi> )? )?
                  | "wasm32"
<os>            ::= "linux" | "darwin" | "win32" | "freebsd" | "openbsd"
                  | "android" | "sunos" | "aix"
<arch>          ::= "x64" | "arm64" | "arm" | "ia32" | "ppc64" | "s390x"
                  | "riscv64" | "loong64"
<abi>           ::= "glibc" <floor version>? | "musl" <floor version>? | "msvc"
<qualifier>     ::= <floor> | <exact tag> | <feature>
<floor>         ::= ( "osv" | "napi" ) <floor version>
<floor version> ::= "." <numeric identifier> ( "." <numeric identifier> )?
<exact tag>     ::= ( "node" | "electron" ) "." <numeric identifier>
<feature>       ::= <build identifier>