Note from the publisher: You have managed to find some of our old content and it may be outdated and/or incorrect. Try searching in our docs or on the blog for current information.

With the release of Npm@5 and NodeJS V8, some of the information below is out of date.

The JavaScript world changes every second. To say a lot has happened in the past year would be an understatement. Among those changes was that Angular2 was released, Node.js 7.0.0 was released, and the feature set for ECMAScript 2016 (ES7) was finalized. In October 2016, Facebook, Exponent, Google, and Tilde released something unexpected, an npm replacement they dubbed Yarn.

Npm Problems and Yarn Solutions

Yarn isn’t a fork of npm but rather a reimagining of it. Large projects–like the ones Facebook and Google have–magnify the issues developers might face when using npm.

Potential problems with npm

  • nested dependencies (fixed in npm 3)
  • serial installation of packages
  • single package registry (npmjs.com ever go down for you?)
  • requires network to install packages (though we can create a makeshift cache)
  • allows packages to run code upon installation (not good for security)
  • indeterminate package state (you can’t be sure all copies of the project will be using the same package versions)

Yarn solutions

  • multiple registries - Yarn reads and installs packages from both npmjs.com as well as Bower. In the event one goes down, your project can continue to be built in CI without issue
  • flat dependency structure - simpler dependency resolution means Yarn finishes faster and can be told to use a single version of certain packages, which uses less disk space
  • automatic retries - a single network request failing won’t cause an install to fail. Requests are retried upon failure, reducing red builds due to temporary network issues
  • parallel downloads - Yarn can download packages in parallel, reducing the time builds take to run
  • fully compatible with npm - switching from npm to Yarn is a no friction process
  • yarn.lock - keeps dependencies locked to specific versions similar to Gemfile.lock in the Ruby world

yarn.lock

Yarn introduces a lockfile, yarn.lock, to manage JavaScript packages. This is possibly the most useful feature of Yarn for developers working in teams. In package.json, package versions could be specified as a range, or without a version at all. This can cause an issue where different developers on the same team are using different versions of the same package. Any CI-trained engineer knows that the ability to reproduce an environment, with the exact same dependencies, is crucial for efficient debugging and onboarding of new team members. Borrowing from package managers such as Bundler, Yarn creates a yarn.lock file that records the exact version of every package you are using for your project. Committing this lockfile to your VCS ensures that all developers working on the project, if they are using Yarn, will be using the same versions of every package.

Using Yarn on CircleCI

Switching from npm to Yarn is painless since they’re compatible. We first wrote about Yarn in December where we showed the best way to download and install Yarn for use in your builds. Since then, we have continued to show our support for Yarn: Yarn is now pre-installed in our CircleCI Ubuntu 14.04 (trusty) image. Yarn can be used on CircleCI the same way as your local environment, by simply using the yarn command. Instructions for caching can be found in our Yarn doc.

npm to Yarn Cheatsheet

npm Yarn
npm install yarn
- install project dependencies from package.json
npm install [package] n/a
- install a specific package without saving it as a dependency in package.json
npm install --save [package] yarn add [package]
- install a package and save it in package.json as a dependency
npm install --save-dev [package] yarn add [package] [--dev/-D]
- install a package and save it in package.json specifically as a development dependency
n/a yarn add [package] [--peer/-P]
- install a package and save it in package.json specifically as a Yarn peer dependency
npm install --save-optional [package] yarn add [package] [--optional/-O]
- install a package and save it in package.json specifically as an optional dependency
npm install --save-exact [package] yarn add [package] [--exact/-E]
- install a specific version of a package, instead of the default behavior of installing the latest version
n/a yarn add [package] [--tilde/-T]
- install the latest minor release of a package with a specified major version (i.e. yarn add foo@1.2.3 -T would install the latest version matching 1.2.x)
npm install --global [package] yarn global add [package]
- install a package globally on your local machine, typically for developer tools
npm rebuild yarn install --force
- rebuilds all packages, even if already downloaded
npm uninstall [package] n/a
- uninstalls a package, but does not remove it from package.json
npm uninstall --save [package] yarn remove [package]
- uninstalls a package and removes it from package.json (regardless of dependency type in Yarn)
npm uninstall --save-dev [package] n/a
- uninstalls a package and removes it as a development dependency from package.json
npm uninstall --save-optional [package] n/a
- uninstalls a package and removes it as a optional dependency from package.json
rm -rf node_modules && npm install yarn upgrade
- upgrades packages to their latest versions

Summary

Yarn addresses issues such as indeterminate dependencies, network issues/npmjs being down, and parallel downloads in order to provide more value over npm. Npm, however, is a victim of its own success. As more people shift over to Yarn and other registries, npm servers can be more available. Both package managers are great and eventually lead to improving one another.

Fun fact: On your local machine, npm can install Yarn! npm install --global yarn. The Yarn Team does not recommend this method of installation.