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

29
votes

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:

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

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?

3
npmversion-controlpackage.jsonpackage-lock.json
Your team should have agreed to solely follow the "current working" module versions in your package-lock.json every time there's a code change unless you all agree that a current module needs to be upgraded. This way, package-lock.json let everyone know which module version is required and "currently working" with your application. – winux

3 Answers

11
votes

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.

4
votes

Create a .gitattributes entry:

# common settings that generally should always be used with your language specific settings

# Auto detect text files and perform LF normalization
* text=auto

#
# The above will handle all files NOT found below
#

#*.svg text
*.lock binary

Then when you merge you will only have to choose a version vs code merges. Thought you might run into package conflicts this way.

We have mitigated that by checking versions in the build process.

2
votes

IMO package-lock.json (or yarn-lock.json) should always be committed to source control. Merge/rebase conflicts aside (which are largely mitigated by yarn BTW - you can yarn install mid-rebase to resolve issues automatically), it is the best guarantee you have that the code at that commit will build and run correctly after a fresh checkout and install.