Should I commit yarn.lock and package-lock.json files?

We're using yarn for all our deterministic pkg installations but don't prevent the user from using npm - I'm guessing having both these files will cause issues however. Should one be added to your .gitignore dir?


Always commit dependency lock files in general

As is covered elsewhere, dependency lock files, which are supported by many package management systems (e.g.: composer and bundler), should be committed to the codebase in end-of-chain projects - so that each individual trying to run that project is doing so with exactly the tested set of dependencies.

It's less clear whether lock files should always be committed into packages that are intended to be included in other projects (where looser dependencies are desirable). However, both Yarn and NPM (as covered by @Cyrille) intelligently ignore yarn.lock and package-lock.json respectively where necessary, making it safe to always commit these lockfiles.

So you should always commit at least one of yarn.lock or package-lock.json depending on which package manager you're using.

Should you commit both yarn.lock and package-lock.json?

At present we have two different package management systems, which both install the same set of dependencies from package.json, but which generate and read from two different lockfiles. NPM 5 generates package-lock.json, whereas Yarn generates yarn.lock.

If you commit package-lock.json then you're building in support for people installing your dependencies with NPM 5. If you commit yarn.lock, you're building in support for people installing dependencies with Yarn.

Whether you choose to commit yarn.lock or package-lock.json or both depends on whether those developing on your project are only using Yarn or NPM 5 or both. If your project is open-source, the most community-friendly thing to do would probably be to commit both and have an automated process to ensure yarn.lock and package-lock.json always stay in sync.

Update: Yarn have now introduced an import command which will generate a yarn.lock file from a package-lock.json file. This could be useful for keeping the two files in sync. (Thanks @weakish)


This issues was discussed at length on the Yarn project in:

  • "Idea: support package-lock.json from npm 5"
  • "Competing lockfiles create poor UX"

Both are now closed.


You should commit 1 dependency tree lock file, but you shouldn't commit both. This also requires standardizing on either yarn or npm (not both) to build + develop a project with.

Here's the yarn article on why yarn.lock should be committed, if you standardize on yarn.

If you commit both the yarn.lock file, AND the package-lock.json files there are a lot of ways that the 2 files can provide different dependency trees (even if yarn's and npm's tree resolution algorithms are identical), and it's non-trivial to ensure that they provide exactly the same answer. Since it's non-trivial, it's unlikely that the same dependency tree will be maintained in both files, and you don't want different behavior depending on whether the build was done using yarn or npm.

If and when yarn switches from using yarn.lock to package-lock.json (issue here), then the choice of lock file to commit becomes easy, and we no longer have to worry about yarn and npm resulting in different builds. Based on this blog post, this is a change we shouldn't expect soon (the blog post also describes the differences between yarn.lock and package-lock.json.


I was thinking about the same question. Here are my thoughts, hope it helps :

The npm package-lock.json documentation says the following :

package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json. It describes the exact tree that was generated, such that subsequent installs are able to generate identical trees, regardless of intermediate dependency updates.

This is great because it prevents the "works on my machine" effect.

Without this file, if you npm install --save A, npm will add "A": "^1.2.3" to your package.json. When somebody else runs npm install on your project, it is possible that the version 1.2.4 of A has been released. Since it is the latest available version that satisfies the semver range specified in your package.json, it will install this version. But what if there's a new bug introduced in this version ? This person will have a problem that you can't reproduce because you have the previous version, without any bug.

By fixing the state of your node_modules directory, package-lock.json file prevents this problem because everybody will have the same versions of every packages.

But, what if you're writing and publishing a npm module ? The documentation says the following :

One key detail about package-lock.json is that it cannot be published, and it will be ignored if found in any place other than the toplevel package.

So, even if you commit it, when the user installs your module, he/she will not get the package-lock.json file, but only the package.json file. So npm will install the latest version that satisfies the semver ranges of all your dependencies. It means that you always want to test your module with theses verions of your dependencies, and not the one you installed when you started writing your module. So, in that case, package-lock.json is clearly useless. More, it can be annoying.


Here's my rule of thumb: if you are working on an application, commit the lock file(s). If you are maintaining a library, add it to your ignored list. Either way you should be using accurate semver ranges in package.json. Yehuda Katz (cached) wrote a great explanation for when to commit Gemfile.lock (Ruby's lock file) and when to not. At least read the tl;dr section.