What is the point of putting npm's "package-lock.json" under version control?

Question

What is the point of putting npm's package-lock.json under version control? In my experience having this file source controlled has caused more trouble and confusion than efficiency gains.

Having package-lock.json under source control makes for a major headache every time a developer who added/removed/modified any node modules needs to resolve conflicts between branches. Especially working on a complex/large apps where the package-lock.json can be tens of thousands of lines long. Even just blowing away node_modules and running a fresh npm install can generate drastic changes in the package-lock.

There are several other SO questions about the package-lock:

• Do I commit the package-lock.json file created by npm
• Npm - package-lock.json role
• Why does npm install rewrite package-lock.json?

And a GitHub issue with a ton of conversation about package-lock:

• package-lock.json file not updated after package.json file is changed

Which makes me think there is still widespread uncertainty that needs cleared up.

According to the docs

package-lock.json is automatically generated for any operations where npm modifies either the node_modules tree, or package.json.

So why would you ever want to put an automatically generated file under source control?

The above GitHub issue details how some people, in response to confusion with the package-lock.json, change their npm install script to rm -f package-lock.json && npm install, which also does not feel correct.

It seems like package-lock.json is striving to be the source of truth for the exact version of node module dependencies, but isn't that exactly what the package.json does? When does the excruciating pain of resolving merge conflicts in this file start to pay off?

Answer 1

In my experience, it does not make sense to put package-lock.json under version control. It makes managing large merge/rebases a nightmare. However, there are instances where the package-lock can be very useful.

Recently (2017/10/10) moment.js introduced breaking changes in a minor version update. Meaning if one was to ship with no package-lock.json, and had something like this in their package.json:

"moment": "^2.12.0"

Some breaking changes introduced in version 2.19.0 would silently infiltrate your code with almost no trace.

This is why after cutting a branch to serve as a release candidate it is crucial to:

• remove package-lock.json from .gitignore
• run npm install to generate a package-lock.json
• test, qa, deploy with this package-lock

This assures your npm module versions will remain locked down on the same versions that were tested.