A team's lockfile was generated by a CI runner on Linux x64. After adding a package that ships native/platform-specific optional dependencies (like a bundler such as esbuild or an image library such as sharp), engineers on macOS ARM report install failures or a missing native binary, even though everyone is using the same committed lockfile. What's causing this, and how do modern lockfile formats address it?

## Native code breaks 'same bytes everywhere' This scenario surfaces a subtlety in what 'reproducible' actually means once native code enters the picture. Most JavaScript dependencies are pure, platform-independent code, so 'reproducible install' simply means 'same JS bytes everywhere.' But some packages need to ship compiled native binaries -- bundlers written in Go/Rust like esbuild, image-processing libraries like sharp that wrap native codecs, or compression libraries using native bindings -- and a single binary can't run on every OS/CPU combination. The ecosystem's solution is to publish one lightweight 'meta' package plus a family of tiny platform-specific packages, each containing only the binary for one OS/CPU pair, each tagged with `os` and `cpu` fields in its own manifest. The meta package declares all of these as `optionalDependencies`. During install, the package manager 1. checks the current machine's platform/architecture against each optional dependency's declared os/cpu, 2. installs the one that matches, 3. and simply skips the rest. 'Optional' here specifically means 'it's fine if this can't be installed on this platform,' which is exactly the semantic needed since only one variant can ever apply on any given machine. ## Where the recording mechanism broke down The failure the question describes happens when the mechanism recording which platform variants exist at all breaks down rather than the platform-matching logic itself. In older lockfile formats, the lockfile's structure was derived somewhat from what actually got installed and resolved on the machine that generated it, and didn't reliably capture the full set of optional platform variants for packages the generating machine didn't need -- so a lockfile committed from a Linux x64 CI runner might be missing complete resolution metadata for a macOS ARM variant entirely, and a macOS engineer running a strict install against that lockfile could - fail to find an entry to satisfy their platform, or - end up with no native binary installed for that dependency, leading to a runtime error rather than an install-time one. Newer lockfile formats were explicitly redesigned to record the full resolved graph including all platform-tagged optional variants regardless of which platform produced the lockfile, precisely so that any machine can install correctly from one shared, platform-complete lockfile. ## The residual complexity, and where containers bite The trade-off here isn't really a deliberate design choice engineers weigh -- it's closer to a historical gap that got fixed -- but it's worth naming the residual complexity that remains even with modern formats: - the lockfile necessarily grows larger because it has to enumerate every platform variant even though only one will ever actually be installed on any given machine, and - tooling has to correctly implement the platform-matching skip logic, which is an extra category of thing that can have bugs. Docker-based CI is a common place this bites: a multi-stage Docker build that runs a strict install inside a Linux container will correctly pick the Linux native binaries even if the lockfile was generated on a developer's Mac, precisely because the platform-matching happens at install time against the current environment, not by baking in whichever platform generated the file -- but only once lockfiles record all-platform metadata; teams stuck on old lockfile formats or migrating between package managers occasionally still hit exactly this class of bug and see confusing missing-module errors for a native binary at runtime, not install time, because the optional dependency install step silently skipped installing anything for their platform without erroring. ## The practical fix A concrete, well-known real-world instance of this exact pattern is documented in bundlers' and image-processing libraries' own troubleshooting guidance -- both classes of tooling explicitly call out 'wrong platform binary' and 'no matching binary' as common support issues, usually traced to either - an outdated lockfile format, - a lockfile generated inconsistently across CI and local environments, or - a related but distinct cause: a `node_modules` directory shared across containers/hosts with different architectures in a Docker Compose or CI caching setup, where the actually-installed binary from one architecture gets reused on another. The practical fix in all these cases is the same: 1. regenerate the lockfile with a current package manager version that records all-platform optional dependency metadata, 2. avoid caching/sharing `node_modules` (as opposed to the lockfile itself) across differing OS/CPU environments, and 3. let each environment's own install step do its own platform-matching from the shared lockfile.