Course contentsShow
← JavaScript
Lesson 2503 of 2,72351. Package ManagementFree lesson

When Lockfiles Get Out of Sync

Understand common scenarios where package-lock.json conflicts arise and how to resolve them.

When Lockfiles Get Out of Sync

You'll learn: How package-lock.json conflicts happen and the practical steps to resolve them.

The Problem

Your package-lock.json can fall out of sync with package.json in several common scenarios. This creates confusion because npm doesn't know which source of truth to follow—the lock should always reflect what's actually installed based on your package.json constraints.

Common Conflict Scenarios

Multiple People Editing Dependencies

When two developers independently run npm install <package> on different branches, they each generate different lockfile entries. On merge, Git creates conflict markers in package-lock.json—and manually editing these is nearly impossible due to the file's complexity.

Manual package.json Edits

If you directly edit version ranges in package.json without running npm install, the lockfile becomes stale. It still points to old versions that may no longer satisfy your new constraints.

Switching Branches

Checking out a branch with different dependencies leaves your node_modules and lockfile mismatched with the current package.json.

Resolution Strategies

For merge conflicts: Delete package-lock.json entirely and run npm install to regenerate it from the merged package.json. Commit the new lockfile.

For staleness after edits: Run npm install to update the lockfile based on your new package.json ranges.

After branch switches: Run npm ci to delete node_modules and reinstall exactly what the lockfile specifies—or run npm install if you want to update the lock to match package.json.

Key Takeaway: When lockfiles drift, regenerate them with npm install (updates lock to match package.json) or restore consistency with npm ci (installs exactly what lock specifies). Never manually edit the lockfile.