package-lock.json conflict — how to resolve

Quick Answer

# First resolve and stage package.json, then choose a lockfile base
git checkout --ours package-lock.json

# Update the lockfile to match the merged package.json
npm install --package-lock-only

# Verify that a clean install succeeds
npm ci

When this happens

<<<<<<< HEAD
  "lockfileVersion": 3,
=======
  "lockfileVersion": 2,
>>>>>>> feature-branch
# (inside package-lock.json after git merge/rebase)

Two branches modified package-lock.json. Resolve package.json first, then update the lockfile from one known side of the conflict. Deleting the lockfile can change unrelated transitive dependency versions.

Other causes & fixes

Prevent future conflicts with npm-merge-driver

# Install the merge driver
npx npm-merge-driver install --global

# It automatically handles package-lock.json conflicts

Use either side of the conflict as a known base

# Accept your version (HEAD)
git checkout --ours package-lock.json
npm install --package-lock-only

# Accept the incoming version
git checkout --theirs package-lock.json
npm install --package-lock-only

Add package-lock.json to .gitattributes

# .gitattributes — use a custom merge strategy
package-lock.json merge=npm-merge-driver

Regenerate only when the version changes are intentional

Removing the lockfile may select newer transitive dependencies. Review the resulting diff and run the test suite before committing it.

rm package-lock.json
npm install --package-lock-only
npm ci