szemate/package-lock-conflicts.md

Last active May 5, 2025 07:32

Star (41) You must be signed in to star a gist
Fork (12) You must be signed in to fork a gist

Learn more about clone URLs
Clone this repository at <script src="https://gist.github.com/szemate/6fb69c8e3d8cce3efa9a6c922b337d98.js"></script>
Save szemate/6fb69c8e3d8cce3efa9a6c922b337d98 to your computer and use it in GitHub Desktop.

Download ZIP

How to resolve package-lock.json conflicts

Raw

package-lock-conflicts.md

How to resolve package-lock.json conflicts

It is not possible to resolve conflicts of package-lock.json in GitHub's merge tool and you need to do a manual merge.

Update the master branch with the latest changes:
```
git checkout master
git pull
```

Merge your feature branch into master:

git merge mybranch

You will see something like the following message:

Auto-merging package-lock.json
CONFLICT (content): Merge conflict in package-lock.json
Auto-merging package.json
CONFLICT (content): Merge conflict in package.json
Automatic merge failed; fix conflicts and then commit the result.

Open your editor (e.g. VSCode) and:
- Carefully resolve conflicts in package.json (if there is any)
- Ignore the conflicts in package-lock.json
Install packages, which will re-generate package-lock.json:
```
npm install
```
"Test drive" your application to make sure the conflicts in package.json have been resolved correctly.
If the application is able to start up (i.e. there are no missing dependencies), add all changes and finish the merge:
```
git add --update
git commit
```
⚠️ Make sure not to commit the *.orig files!
If everything looks fine, push to GitHub:
```
git push
```

DaveVodrazka commented Sep 28, 2022

Here is a step by step example, that should make it extra clear:

Problem

My library has three dependencies, package a, b and c. My package.json looks like this:

{
  "a": "^1.0.0",
  "b": "^1.0.0",
  "c": "^1.0.0"
}

and my package-lock.json looks like this (notice missing ^):

{
  "a": "1.0.0",
  "b": "1.0.0",
  "c": "1.0.0"
}

This means, that all three dependencies are "locked" at version 1.0.0.

Now, some time has gone by and maintainers of my dependencies have published newer versions. In the npm repository the latest versions are now a: 1.2.1, b: 1.3.4 and c: 1.0.7.

I need to bump package c to version 1.0.7 to fix some bug. I run npm install c and merge changes. package.json now looks like this:

{
  "a": "^1.0.0",
  "b": "^1.0.0",
  "c": "^1.0.7"
}

and pakcage-lock.json like this:

{
  "a": "1.0.0",
  "b": "1.0.0",
  "c": "1.0.7"
}

Someone else decides to bump package b to fix a different bug. They checkout their own branch and run npm install b, which bumps pakcage b to 1.3.4. Their package.json looks like this:

{
  "a": "^1.0.0",
  "b": "^1.3.4",
  "c": "^1.0.0"
}

and pakcage-lock.json like this:

{
  "a": "1.0.0",
  "b": "1.3.4",
  "c": "1.0.0"
}

They try to merge, but run into a conflict. They easily resolve conflict in package.json like this:

{
  "a": "^1.0.0",
  "b": "^1.3.4",
  "c": "^1.0.7"
}

So that both package b and c are at the appropriate version. All that is left to do is to resolve conflict in the package-lock.json.

And this is where we run into the problem, because the package-lock.json that we should have locks versions like this:

{
  "a": "1.0.0",
  "b": "1.3.4",
  "c": "1.0.7"
}

But if you were to run npm install now, the pakcage-lock.json you'd end up with would lock these versions:

{
  "a": "1.2.1",
  "b": "1.3.4",
  "c": "1.0.7"
}

Notice that, while nobody bumped package a, we ended up with a new version "a": "1.2.1".

Explanation

Now why is that? Since the version in our package.json is set to "a": "^1.0.0", the ^ symbols tells npm to keep both minor and patch version up to date, ie. if there is newer minor or patch version, it will be downloaded and updated in package-lock.json.

Theoretically, this should not be a problem, because patch should never break anything and minor version update should always be backwards compatible, but since versioning is done by people and people are prone to making mistakes - this does not always hold true.

This is why running npm install to resolve package-lock.json conflits is not a bulletproof strategy.

I don't have a better solution and I do use this way of fixing the conflicts, but you should be aware of potential problems this may introduce.

cjones26 commented Sep 28, 2022 •

edited

Loading

@DaveVodrazka 👏 bravo--excellent explanation.

In regards to this entire conversation, I posed a similar question regarding the maintenance of package-lock.json files to a contributor of npm ~2 weeks ago here: npm/cli#4844 (comment).

Since npm v6 there is no longer any mention about how to resolve lockfile conflicts within the npm documentation, though it appears the appropriate solution is to utilize something like parse-conflict-json. I haven't looked into it much but it may be the solution we are all looking for, it would just be helpful is the npm team would actually codify some of this in their documentation.