Today, we are excited to announce the 1.0 release of the Yarn JavaScript package manager, a major step for the project. In the 11 months since its initial release, Yarn has generated a large following. Currently, there are more than 175,000 projects on GitHub with a yarn.lock file in their root directory. In use by many large and small companies, and across the open source community, Yarn is now responsible for nearly 3 billion package downloads per month. Reduced install times are a big draw for many users. Twitter, as well as Microsoft on outlook.com, have seen improvements of 5x in install times. Expo, Kenzan, and Sentry have reported performance and stability improvements so they can ship code faster. Additionally, Yarn now also comes pre-installed on major continuous integration platforms such as CircleCI, Travis CI, and AppVeyor.

Here at Facebook, Yarn has been adopted across many codebases including the main Facebook app and website, Instagram, Oculus, and WhatsApp. Yarn supports hundreds of thousands of package installs on our systems every day. It was designed to scale even when a project has hundreds or thousands of direct or transitive dependencies. Installs are done quickly and securely using the offline mirror feature, and they are reliable and reproducible not only on the different machines of our engineers, but also across our continuous integration systems.

We’re thrilled with the adoption and community engagement. Yarn’s main focus when we launched almost a year ago was stability, resiliency, and performance. Building on the core principles of what made Yarn successful in the first place, the 1.0 release comes with many new features that we hope will help the Yarn community move faster and build great projects. The project’s source code and website have received significant contributions from the open source community, and many of the features in Yarn 1.0 were designed and implemented by the community members.

What ‘s new in 1.0

Yarn Workspaces

We have seen the mono-repository approach for source control, popularized by large tech companies such as Facebook, slowly gain traction within the open source community and smaller companies. One reason for the shift is that this paradigm makes it easier to share code across all projects while avoiding dependency synchronization issues. To make it easier for people to start adopting this pattern, Yarn added a new feature: Workspaces. It lets people automatically aggregate all the dependencies from multiple package.json files and install them all in one go. It also uses a single yarn.lock file at the root, to lock them all. Moreover, Yarn will create symlinks between all Workspaces that happen to depend on one another, so that in the end, the latest code is always used across all projects.

Workspaces are already used by some teams at Facebook and projects like Babel in the open source community. If you are using Lerna, a popular mono-repository management tool, you can opt in to use Yarn’s Workspaces. The pull request to switch Babel to Workspaces is a good example to get you started. By making Workspaces native to Yarn, we hope to enable faster and lighter installations by preventing package duplication between the smaller parts of a larger project.

Auto-merging of lockfiles

On fast-paced projects with multiple contributors, dependencies can get updated in separate pull requests one after another. As a result, it is possible to end up with a merge conflict in the yarn.lock file. When this happens with only one or two packages, it is generally straightforward to resolve the conflicts manually. However, if there are more than a handful, resolving the conflicts may become a tedious task.

With the new auto-merge feature in Yarn, when there’s a merge conflict in the lockfile, Yarn will automatically handle the conflict resolution for you upon running yarn install. If it succeeds, the conflict-free lockfile will be saved to disk, leaving you only the task of marking it as resolved in your version control system.

The next time you have a lockfile conflict, you can save time by running yarn install instead of doing a manual resolution:

Selective version resolutions

Occasionally, packages will receive important bug fixes or critical security updates that need to be adopted as soon as possible. Unfortunately, your project may not be the direct consumer of those dependencies, but rather will use them through a few layers of transient dependencies. In such cases, you’ll be forced to either wait until your direct dependency is updated, or fork it and update the dependencies manually until a new release. Neither option is ideal. The selective version resolution feature in Yarn was developed to provide a better solution to these kinds of problems

Yarn now allows defining a resolutions field in a project’s package.json file that instructs Yarn to use specific versions of certain sub-dependencies, regardless of the original patterns its dependents set. This feature is flexible and generic enough to define granular rules via glob patterns to reach deep into specific transient dependencies. Here is an example of what that feature may look like if you’d like to limit sub-dependencies to a specific version of the async module:

It is important to note that this feature was completely designed and implemented by community members. The RFC and acceptance tests were submitted by Victor Noël, and a full end-to-end implementation came from Kaylie Kwon.

Fixes and other improvements

On top of these new features, we’d like to mention a number of other improvements:

  • A better interactive upgrade experience.
  • A faster file integrity check.
  • A separate lockfile parser module that you can use in your project.
  • The ability to defer to another Yarn binary for consistency.
  • Many more fixes and features that went into Yarn 1.0.
  • The complete changelog.

Community involvement

Yarn 1.0 wouldn’t have happened without the support of the open source community. Yarn was created as an independent Organization on GitHub — a collaborative effort from multiple companies — and was quickly adopted by the larger JavaScript community.

Shortly after the initial launch of the project, we introduced an RFC process to encourage and discuss community contributions. Many of the features mentioned above were initially conceived and later implemented by members of the community. More than 40 contributors made impactful changes to the project in 2017 so far. Here are some of the highlights:

  • Haroen Viaene and Vincent Voyer from Algolia proposed building a lightning-fast package search feature and beautiful package detail pages for the Yarn website to make finding the right packages for your applications easier.
  • Kat Marchán, who is from npm Inc. and works on the npm client, contributed a change that significantly improved file copying operations in Yarn.
  • Both RFCs and implementations were made for features such as offline mirror pruning (implementation), consistent UX for the upgrade command ( implementation), and selective version resolutions (implementation).
  • William Hilton stepped in and separated the lockfile parser into a standalone module: @yarnpkg/lockfile.
  • Jerel Unruhproposed and Greg Thornton added yarn import for switching to Yarn without surprises.
  • Rifat Nabi implemented yarn upgrade-interactive to update dependencies interactively in the CLI.

What’s next?

Development on Yarn will continue. Here are a few key points we’d like to see in the future. If you feel as excited as we do about these features, please get engaged with the community and start contributing!

Yarn release

Maintaining open source projects isn’t easy. Releasing a new package usually involves creating proper change logs, performing correct semantic versioning, syncing versions in related projects, and taking other steps that frequently are handled manually by maintainers or with custom scripts. Wouldn’t it be great if Yarn supported library authors with all the grunt work?

Package security

Package review is an important step when adding new packages or upgrading old ones. We’d like to see Yarn play a role to increase confidence in the packages being installed. We are going to work with npm to bring two-factor authentication to Yarn to make some progress on this front.

Semver

With the 1.0 release, we are committed to not making any breaking changes in minor or patch releases. This requires extra attention on our side, more help from tooling, and streamlined release processes, which we aim to put in place in the near future.