Yarn Explained: Facebook’s Faster, Safer JavaScript Package Manager

npm hosts over 300,000 packages and serves more than 5 billion downloads per month. Facebook engineers encountered three core problems as their codebases grew: inconsistent installations across machines, long install times, and security risks from automatically executed lifecycle scripts.

Initial mitigation attempts included:

Committing only package.json and running npm install manually. This worked locally but failed in sandboxed CI environments that require network isolation.

Committing the entire node_modules directory. A minor version bump of Babel generated an 800 000‑line commit, and a React Native project with 68 declared dependencies produced 121 358 files after npm install, inflating repository metadata and consuming a full day of engineer time for merges.

Compressing node_modules into a CDN‑hosted archive. The archive removed the bulk from version control but forced every checkout and build to maintain network connectivity.

Using npm’s shrinkwrap file. The generated JSON was unordered, huge, and produced massive, hard‑to‑review commits; additional scripts were required to sort the fields.

Relying on semver, which caused a single dependency update to pull in many unrelated transitive updates.

Concluding that patching npm would not resolve the fundamental issues, Facebook’s London office, led by Sebastian McKenzie, collaborated with engineers from Exponent, Google, and Tilde to create Yarn, a new client compatible with the npm registry but designed for speed, reliability, and security.

Architecture and Core Design

Yarn introduces a deterministic yarn.lock file that records the exact version of every resolved dependency. The lockfile’s fields are ordered, ensuring minimal, review‑friendly diffs and guaranteeing identical node_modules layouts on every machine.

The installation algorithm is explicitly divided into three steps:

Resolve : Yarn parses the dependency graph and recursively queries the registry for each package.

Fetch : Yarn checks a global cache directory for the required tarball; missing packages are downloaded once and stored for offline reuse. Packages can also be stored as tarballs in version control to achieve fully offline installs.

Link : Cached files are copied into the project’s node_modules directory, producing a consistent layout.

This decomposition eliminates nondeterministic outcomes and enables parallel operations. On Facebook projects, Yarn reduced install times from several minutes to a few seconds—a magnitude‑level improvement. Yarn also enforces strict security: lifecycle scripts can be disabled per package, and checksums are stored in the lockfile to verify package integrity.

Additional Features

Full compatibility with npm and Bower workflows, supporting mixed repositories.

Ability to restrict and report dependency license types.

Stable JavaScript API for integration with other build tools.

Clean, minimal, and readable CLI output.

Production Adoption

Facebook runs Yarn in production across many JavaScript projects, providing offline capabilities and faster workflows. A public comparison page (https://yarnpkg.com/en/compare) documents Yarn’s installation‑time advantages over npm under various conditions.

Getting Started

npm install -g yarn

yarn

After installation, common npm commands map directly to Yarn equivalents: npm install →

yarn

npm install --save <name>

→ yarn add <name> Yarn removes npm’s “implicit dependency” behavior, keeping only explicit installations.

Future Outlook

Yarn is open‑source on GitHub, and the project invites community contributions to continue improving the tool for the broader Node ecosystem.