Yarn: A package manager for Node.js

Ruby has Bundler.

PHP has Composer.

Rust has Cargo.

Python has pip.

These package managers automate the process of installing and managing libraries and dependencies.

In Node.js, we have npm as the default package manager, which is automatically included when Node.js is installed.

Npm is not perfect, and there are a number of open source alternatives created to solve some of its issues like ied, pnpm, and more recently, yarn

Yarn was released by Facebook in collaboration with Exponent, Google, and Tilde in October 2016.

There's a post on Facebook Code that describe the reasons for building this new package manager.

Here are some highlights:

... as we scaled internally, we faced problems with consistency when installing dependencies across different machines and users, the amount of time it took to pull dependencies in, and had some security concerns with the way the npm client executes code from some of those dependencies automatically.

We also had to work around issues with npm's shrinkwrap feature, which we used to lock down dependency versions.

... updating a single dependency with npm also updates many unrelated ones based on semantic versioning rules.

Many advantages of using Yarn aren't common knowledge yet. This guide will explore the advantages of Yarn over npm and will cover some basic commands that will help new users settle into using Yarn regularly.

Here's Yarn's Github page. It's a pretty popular project; at the time of this writing, it has 21,500 stars and more than 500 open issues. Yarn is compatible with the npm registry and has the same set of features as npm, but it operates faster and in a more reliable way. Let's take a look.

You can install yarn with npm but this is not recommended:

Instead, if you're on Windows, download the installer (you need to have Node.js installed).

If you're using iOS or a Unix environment, the easiest way is via a shell script:

In this page you can find more information and other installation methods.

As we know, Node.js dependencies are placed in the node_modules directory of your project.

These dependencies are installed in a non-deterministically way, which means that the directory structure and dependency tree depend on the order dependencies are installed. Such a dependency is problematic because it can differ from machine to machine.

To solve this issue, Yarn uses a lockfile (yarn.lock) to ensure that everyone has the same version of every single file, resulting in the exact same file structure of the node_modules directory across all machines.

When dependencies are resolved, Yarn first looks in a local (global) cache to see if the package has been downloaded already. This, with Yarn's ability to efficiently queue up and parallelize requests, makes Yarn faster than npm.

So let's test it.

The comparisons outlined here were made using npm 4.05 and Yarn 0.18.1.

To initialize a project with npm we use npm init:

Yarn has the same init command, but with a slightly different set of questions and answers:

To install a dependency and save it to package.json, for example express (which has more than twenty dependencies), in npm we execute:

Using Yarn:

One little advantage of using Yarn is that you have to type less. Well, as long as you're not using aliases like npm i -S express.

But let's time the execution of these commands.

Npm:

Yarn:

As you can see from the images, npm took 3.120 seconds, while Yarn took 2.588 seconds.

You can also see that the output of Yarn is more descriptive and prettier. The emojis are only available on Mac though.

Now, let's delete the node_modules directory and repeat the test to see Yarn's caching in action:

This time, Yarn took 1.455 seconds, an improvement of 44% over the previous execution. And 53% over npm.

Of course, you may get different results, but Yarn will beat npm every time.

We can also see that a yarn.lock file is generated (some parts are omitted for shortness):

Notice that Yarn uses https://registry.yarnpkg.com instead of https://registry.npmjs.org.

In a podcast episode of NodeUp (around the 40:30 mark) James Kyle (one of the main developers of Yarn) said that, for now, registry.yarnpkg.com is just a CNAME record that goes to the Cloudflare network and redirects to the NPM registry for experimental purposes, and to add some performance features.

Now compare it to the file npm-shrinkwrap.json (which serves a similar purpose than yarn.lock), generated when npm shrinkwrap is executed (some parts are omitted for shortness):

The advantage of using Yarn is that yarn.lock is generated automatically; with npm you have to execute npm shrinkwrap manually.

One important thing, yarn.lock should always be added to source control. Remember that this file ensures the deterministic installation of the dependencies.

Now, if you specify a package version, you'll notice an important difference in the generated package.json file.

For example, if you execute:

It will generate:

Executing:

Will generate:

Did you notice the missing caret(^) in Yarn's package.json file?

Many people recommended not using carets in our package.json files.

The caret will update the dependency to the most recent minor version when it's installed. For example, if there's a 2.4.1 version available, this will be installed even if ^2.3.1 is the one specified. This can cause trouble in some cases because sometimes breaking changes are introduced even in minor releases.

If you want to specify an exact version rather than using npm's semantic version range operator (the caret), you have to use the --save-exact (or its alias -E), as in:

However, that's something you have to know and keep in the back of your head. On the other hand, Yarn does this "caret-handling" for you. If this is something you want, it depends of your preferences and the libraries you're using.

Moving forward, if you already have a package.json file, you can install the dependencies with:

Or just:

If you want to remove a dependency and update the package.json file to reflect that, with npm you need to execute:

With Yarn, you need to execute:

That will update your package.json and yarn.lock files by default.

The command yarn upgrade [package] will upgrade all the packages (or a single named package) to their latest version (some rules apply), and using yarn upgrade package@version will upgrade (or downgrade) an installed package to the specified version. In all cases, the yarn.lock file will be recreated as well.

Next I'll cover a key difference between npm and Yarn.

One feature missing on Yarn is an equivalent of npm dedupe, a command to reduce duplicated dependencies. Since a project can have many versions of the same dependency, this dedupe command can come in handy.

For background, npm dedupe searches the dependency tree and attempts to simplify the overall directory structure by moving dependencies further up the tree (even if duplicates are not found), where they can be more effectively shared by multiple dependent packages. If a suitable version already exists at the target location, it will be left untouched, but the other duplicates will be deleted. This will result in both a flat and deduplicated tree.

On the other hand, the Yarn install command has a --flat flag:

On the first run, it will prompt you to choose a single version for each package that has more than one version on the dependency tree. These will be added to your package.json under a resolutions field. But this is not the same as npm dedupe, which removes duplicates by deletion.

This difference means that the node_modules directory generated by Yarn could take more space on disk than the one generated by npm.

However, this tradeoff might not impact you, your workflow, or your business significantly.

This section covers other Yarn commands that you should know. You can see the complete list of Yarn commands and their options here.

For one, Yarn comes with a license checker. It will give you the license (and URL to the source code) associated with each package:

In addition to ls, yarn licenses generate-disclaimer will output the content of all licenses from all the packages you have installed.

To fetch information about a package, use yarn info:

You can also ask for the version information, such as the currently installed version, the desired version based on semver, and the latest available version, of one or more packages of your packages.json file:

Finally, Yarn can show information about why a package, package folder, or file within a package folder is installed:

Yarn is already used in production at Facebook. Furthermore, as demonstrated in this guide, it's a great high-performance alternative to npm.

For simple personal projects, perhaps the one you use doesn't make much of a difference. However, for bigger projects (and depending on your needs), Yarn might provide a clear advantage over the alternatives.