What is the purpose of the package-lock.json file, and should it be committed?

If I had to summarize in a few words the role of the package-lock.json file, I would say that it serves to store an exact representation of the dependencies installed in the project at a given moment.

But another question then arises:

Why would we need to know the exact state of the project's dependencies when we already have the package.json file for that?

Simply because the package.json file doesn't index the installed packages but merely contains rules for installing them according to a more or less precise version indication.

By using version numbers like "latest", "~1.1.0" or "^1.1.0", it's impossible to predict which exact version will ultimately be installed.

We say that running the npm install command is "non-deterministic" because running it multiple times can produce different results.

So here's a behavior that can cause problems when two developers on the same team end up with two different dependency folders, despite both coming from the same package.json

This is why, since version 5 of NPM, two new features have appeared:

• the package-lock.json file
• the npm ci command

package-lock.json

The package-lock.json file lists all installed dependencies, with for each one:

• the exact version
• the url from which it was installed
• a checksum to verify integrity
• the sub-dependencies

This allows for a very precise instant snapshot of the dependencies currently used by the project, which will be updated with every operation that modifies the content of node_modules or the package.json file

Installing from cache

NPM

The npm ci command is the equivalent of the npm install command, but instead of fetching each dependency from the registry (for example registry.npmjs.org), it will first look in the cache (making it much faster for redeployments), and it won't be based on the package.json file, but rather on the package-lock.json file

In addition to execution speed, this command makes it possible for example to restore a previous state of an application (even one dating back several months), and to be able to find each dependency in its original version, even if many versions have been released since then.

$> npm ci

This is why the package-lock.json file is very useful, and this is also the reason why you absolutely must add it to your commits in your various projects!

Yarn

Yarn has an equivalent, but this time instead of being a different command, it's an option passed during dependency installation:

$> yarn install --frozen-lockfile

PNPM

It's the same thing with PNPM, which has the same option as Yarn:

$> pnpm i --frozen-lockfile