Should I commit the yarn.lock file and what is it for?

Depends on what your project is:

1. Is your project an application? Then: Yes
2. Is your project a library? If so: No

A more elaborate description of this can be found in this GitHub issue where one of the creators of Yarn eg. says:

The package.json describes the intended versions desired by the original author, while yarn.lock describes the last-known-good configuration for a given application.

Only the yarn.lock-file of the top level project will be used. So unless ones project will be used standalone and not be installed into another project, then there's no use in committing any yarn.lock-file – instead it will always be up to the package.json-file to convey what versions of dependencies the project expects then.

I see these are two separate questions in one. Let me answer both.

Should you commit the file into repo?

Yes. As mentioned in ckuijjer's answer it is recommended in Migration Guide to include this file into repo. Read on to understand why you need to do it.

What is yarn.lock?

It is a file that stores the exact dependency versions for your project together with checksums for each package. This is yarn's way to provide consistency for your dependencies.

To understand why this file is needed you first need to understand what was the problem behind original NPM's package.json. When you install the package, NPM will store the range of allowed revisions of a dependency instead of a specific revision (semver). NPM will try to fetch update the dependency latest version of dependency within the specified range (i.e. non-breaking patch updates). There are two problems with this approach.

1. Dependency authors might release patch version updates while in fact introducing a breaking change that will affect your project.

2. Two developers running npm install at different times may get the different set of dependencies. Which may cause a bug to be not reproducible on two exactly same environments. This will might cause build stability issues for CI servers for example.

Yarn on the other hand takes the route of maximum predictability. It creates yarn.lock file to save the exact dependency versions. Having that file in place yarn will use versions stored in yarn.lock instead of resolving versions from package.json. This strategy guarantees that none of the issues described above happen.

yarn.lock is similar to npm-shrinkwrap.json that can be created by npm shrinkwrap command. Check this answer explaining the differences between these two files.

You should:

1. add it to the repository and commit it
2. use yarn install --frozen-lockfile and NOT yarn install as a default both locally and on CI build servers.

(I opened a ticket on yarn's issue tracker to make a case to make frozen-lockfile default behavior, see #4147).

Beware to NOT set the frozen-lockfile flag in the .yarnrc file as that would prevent you from being able to sync the package.json and yarn.lock file. See the related yarn issue on github

(Tough such a workflow is possible with berry, see my edit at the very bottom of this answer.)

yarn install may mutate your yarn.lock unexpectedly, making yarn claims of repeatable builds null and void. You should only use yarn install to initialize a yarn.lock and to update it.

Also, esp. in larger teams, you may have a lot of noise around changes in the yarn lock only because a developer was setting up their local project.

For further information, read upon my answer about npm's package-lock.json as that applies here as well.

This was also recently made clear in the docs for yarn install:

yarn install

Install all the dependencies listed within package.json in the local node_modules folder.

The yarn.lock file is utilized as follows:

• If yarn.lock is present and is enough to satisfy all the dependencies listed in package.json, the exact versions recorded in yarn.lock are installed, and yarn.lock will be unchanged. Yarn will not check for newer versions.
• If yarn.lock is absent, or is not enough to satisfy all the dependencies listed in package.json (for example, if you manually add a dependency to package.json), Yarn looks for the newest versions available that satisfy the constraints in package.json. The results are written to yarn.lock.

If you want to ensure yarn.lock is not updated, use --frozen-lockfile.

If you want to use berry (yarn@4), be aware that the wording changed: --frozen-lockfile is now --immutable:

yarn install --immutable

Though one is now enable this in one's .yarnrc:

enableImmutableInstalls: true

so that a

yarn install

is also immutable, while still being able to force sync the yarn.lock file via:

yarn install --no-immutable

See: https://github.com/yarnpkg/yarn/issues/4570

I also created an gitgub issue for berry to make the immutable the default approach.

Not to play the devil's advocate, but I have slowly (over the years) come around to the idea that you should NOT commit the lock files.

I know every bit of documentation they have says that you should. But what good can it possibly do?! And the downsides far outweigh the benefits, in my opinion.

Basically, I have spent countless hours debugging issues that have eventually been solved by deleting lock files. For example, the lock files can contain information about which package registry to use, and in an enterprise environment where different users access different registries, it's a recipe for disaster.

Additionally, the lock files can really mess up your dependency tree. Because yarn and npm create a complex tree and keep external modules of different versions in different places (e.g. in the node_modules folder within a module in the top node_modules folder of your app), if you update dependencies frequently, it can create a real mess. Again, I have spent tons of time trying to figure out what an old version of a module was still being used in a dependency wherein the module version had been updated, only to find that deleting the lock file and the node_modules folder solved all the hard-to-diagnose problems.

I even have shell aliases now that delete the lock files (and sometimes node_modules folders as well!) before running yarn or npm.

Just the other side of the coin, I guess, but blindly following this dogma can cost you........

From My experience I would say yes we should commit yarn.lock file. It will ensure that, when other people use your project they will get the same dependencies as your project expected.

From the Doc

When you run either yarn or yarn add , Yarn will generate a yarn.lock file within the root directory of your package. You don’t need to read or understand this file - just check it into source control. When other people start using Yarn instead of npm, the yarn.lock file will ensure that they get precisely the same dependencies as you have.

One argue could be, that we can achieve it by replacing ^ with --. Yes we can, but in general, we have seen that majority of npm packages comes with ^ notation, and we have to change notation manually for ensuring static dependency version.But if you use yarn.lock it will programatically ensure your correct version.

Also as Eric Elliott said here

Don’t .gitignore yarn.lock. It is there to ensure deterministic dependency resolution to avoid “works on my machine” bugs.

I'd guess yes, since Yarn versions its own yarn.lock file: https://github.com/yarnpkg/yarn

It's used for deterministic package dependency resolution.

Yes! yarn.lock must be checked in so any developer who installs the dependencies get the exact same output! With npm [that was available in Oct 2016], for instance, you can have a patch version (say 1.2.0) installed locally while a new developer running a fresh install might get a different version (1.2.1).

Yes, you should commit it. For more about yarn.lock file, refer to the official docs here