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.muslare valid;x64alone (arch without os) is not. An omitted axis is no constraint:linux.x64with no abi runs on glibc and musl alike. - An abi of
glibcormuslMAY carry a version floor, the lowest version of that C library the build runs on:linux.x64.glibc.2.28runs on glibc 2.28 or later (themanylinuxrule). - Qualifiers follow the fixed axes, in any order: floors (
osv.11.0for the OS version ondarwinandwin32,napi.8for the N-API version an addon needs), exact tags (node.127,electron.123: theNODE_MODULE_VERSIONan addon was built against; a variant carriesnapior one of these, not both), and feature tags (avx2,cuda,neon), which SHOULD be sorted for a canonical form. wasm32stands 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 key | Values |
|---|---|
os | linux · darwin · win32 · freebsd · openbsd · android · sunos · aix |
arch | x64 · arm64 · arm (ARMv7) · ia32 · ppc64 · s390x · riscv64 · loong64 |
abi | glibc[.M.m] · musl[.M.m] · msvc |
| platform | wasm32, in place of the fixed axes |
| floors | osv.M[.m] · napi.N |
| exact tags | node.N · electron.N |
| features | any 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.x64matcheslinux.x64.musl. To distinguish siblings that share a prefix, make the distinguishing axis explicit: model libc aslinux.x64.glibcvslinux.x64.muslrather 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:
- Each fixed axis it states equals the target's. An omitted axis is no constraint.
wasm32applies to every target. - 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. - Each exact tag it states (
node,electron) equals the target's. - 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:
- a variant that states more fixed axes before one that states fewer;
- then a higher floor before a lower one, and any floor before none;
- then an exact
node/electrontag before anapifloor before neither; - then a variant that states more matched feature tags;
- then a native variant (one with an
os) beforewasm32, andwasm32before 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,napiandnodeAbi, 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
variantsfield (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:The RFC's author order (“narrower first, higher floors first,variantsentryCoordinate os,cpu,libc(one value each)the fixed axes, in order libcVersion: "2.28"glibc.2.28on the abi axis (the RFC's floor implies glibc)osVersion: "11.0"osv.11.0napi: 8napi.8nodeAbi: "node-127"/"electron-123"node.127/electron.123an 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 alla !valueexclusionno 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 entry wasm32, or the build-less releasenodeAbibeforenapi, native before the fallback”) is the specificity order here, so a tool can generate a correctly orderedvariantslist 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>