Migrating from npm to Yarn: A Comprehensive Guide

It is not uncommon to want to migrate a project from npm to yarn. So how exactly does one migrate? The first thing to note is that both yarn and npm can consume the same package.json format, and both of them can install any package from the npm registry.

For most users, the process of migrating from npm to yarn is fairly easy.

You will need to run yarn from your command line, in order use yarn on your existing npm project.

When you run this command, it will lay out your node_modules folder using Yarn's resolution algorithm. This algorithm is compatible with the resolution algorithm of node.js module.

If you get error while trying the above step, you should check if it is an issue that already exists on yarn's issue tracker, if not report it with the issue tracker.

If you run either of yarn or yarn add <package>, yarn generates a yarn.lock file inside the root directory of your package. You should check this file into source control, there is no need trying to understand it.

When other people in your team also switch to yarn from npm, the yarn.lock file ensures that they get exactly the same dependencies that you have.

Usually, when you run yarn or yarn add for the first time, it will work perfectly. However, there are cases where the information in that is contained in the package.json file is not explicit enough to eliminate dependencies, and then the deterministic way that Yarn chooses dependencies run into dependency conflicts. This can occur in larger projects where npm install does not work and the developers are frequently removing the node_modules folder and rebuilding the project from scratch. In such cases, it is advisable that you use npm to make the dependencies more explicit, before you convert to Yarn.

As from Yarn 1.7.0, you can import your project's package-lock.json state that is generated by npm into Yarn, by running yarn import.

When you migrate to Yarn, other developers on the project can keep on using npm, so they don't need to convert to yarn at the same time. All the developers that are using yarn will get the same configuration, while the developers that are still using npm will get a slightly different configuration.

If you later want to switch back to npm, you can do so without making any particular changes. You have to delete your old yarn.lock file if there is nobody in the team using it, but that is not necessary.

You may end up with a different set of dependencies, if you are currently using an npm -shrinkwrap file. There is no support for npm shrinkwrap files in Yarn, this is because shrinkwrap files do not have enough information in them to power the more deterministic algorithm of Yarn.

It may be easier to convert everyone on your project to use Yarn if you are using a shrinkwrap file, all you have to do is to remove your existing npm-shrinkwrap.json. file and then check in the newly created yarn.lock file to source control.

CLI commands comparison

Previous: Selective Dependency Resolutions in Yarn.
Next: Getting Started with Yarn Plug'n'Play.