What is the package-lock.json file for?

What is the package-lock.json file and what does it do?

The regular package.json file contains lots of information about your projects, such as its name, version, and all the packages that your project depends on to work.

The package-lock.json file was introduced in npm version 5. Its purpose is to keep track and lock the exact version of every package that makes up your product. This makes sure that your website or app is always 100% reproducible by you, or a team member, to the same version, even if some of the packages get updated by their maintainers (which is out of your control).

As the file name expresses, it locks your package versions.

Yarn (an alternative to npm) has its own lock file called yarn.lock

If you don’t have a package-lock.json or yarn.lock file in your repository and a new developer joins your team, once they have downloaded your project from your remote repository (e.g. GitHub) and installed it, they will likely be working with different package versions than you.

This is not always a problem, but sometimes it’s a huge problem.

Imagine if you have multiple developers working on the exact same project, but every developer is using slightly different package versions. This can lead to all types of bugs, inconsistencies, performance, and security issues.

The next time you download a repository from GitHub or elsewhere, look for either package-lock.json or yarn.lock in the root directory.

Here’s an example of a GatsbyJS starter website on GitHub by Fabian Schultz that uses a yarn.lock file.

Not all projects have a lock file, but if the one you download does, like the one above, when you run the project on your local machine it will use the same package versions as the project author. This means that if you find a bug with the project, you can tell the project author and he or she should quickly be able to reproduce the bug in their development environment — because the lock file ensures that you are both running on the same package versions.

If you delete the package-lock file, which is very common to do, and then run npm i or yarn, don’t be surprised if the project doesn’t run properly. The author of the project could be working on solving a specific problem that isn’t currently compatible with every newest version of the packages listed in the package.json file.

There’s a lot more to say about package.json and package-lock (or yarn.lock) but this is one of those features of version control that you will only truly understand the importance of once you experience it in practice.