Read the lockfile diff as a list of new code that will run on your build machines. Look for packages that were added, entries whose resolved source changed, entries missing an integrity value, and surprising new maintainers or git sources. Upgrading one build tool can add dozens of lines, so triage by what is new.
Why the diff is worth reading
npm's documentation describes package-lock.json as describing the exact tree that was generated, so later installs produce identical trees regardless of intermediate dependency updates. It lists, as one purpose of the file, giving visibility into tree changes through readable source control diffs. That is exactly the use case here.
When you bump a bundler, transpiler or test runner, the lockfile records everything the new version pulls in. That diff is where an unexpected package first appears.
What each field tells you
From the lockfile documentation, each package entry carries fields you can use in review:
| Field | What it means | What to look for |
|---|---|---|
| version | The version found in package.json | Jumps of a major version in a transitive package |
| resolved | Where the package was actually resolved from. A tarball URL for registry packages, a full git URL with commit for git dependencies, a location for links | A host you do not recognise, a git URL, or a file path |
| integrity | A standard subresource integrity string for the artifact | A missing value on a registry package |
| dev, optional | Flags showing how the package is used | A new optional entry with native code |
The registry value is described as a magic value meaning the currently configured registry, so a change to a private mirror host is visible too.
A review procedure
- Run the upgrade on a branch and commit both package.json and the lockfile.
- In the pull request, filter the diff to lines that start a new package entry. Count additions and removals.
- For each new package, check the name against what you expected. Look for near misses of well known names.
- Search the diff for resolved values that are not your registry. Git sources and file sources deserve a question.
- Look for entries without an integrity value on registry packages.
- Check the new packages for install scripts and native code. See which npm lifecycle scripts run when you install.
- Run the dependency scan on the pull request and read the new findings, not only the total.
- Merge only when CI installs with npm ci.
Why npm ci in CI is part of the review
The npm ci documentation says that if dependencies in the lockfile do not match package.json, it exits with an error instead of updating the lockfile, and that it never writes to package.json or to the lockfile. So the lockfile you reviewed is the one CI installs. If CI used plain npm install, it could resolve something different from what you read. Also, if you generated the lockfile with flags that change the shape of the tree, the docs say you must pass the same flags to npm ci.
What a diff cannot tell you
A clean diff does not prove a package is safe. It shows what changed, not whether the new code is trustworthy. Combine it with checks on maintainers and release age, and with a scanner that knows about malicious packages and advisories. For packages you cannot judge from a diff, see how to check an npm package before you install it.
Making it routine
Teams that review the lockfile in every dependency pull request build a good sense for what normal looks like. A bundler upgrade that adds three packages is routine. One that adds eighty and a new git source is a question for the maintainer. Add a pull request template line that says lockfile reviewed, and have an owner for build tool updates.
Safeguard's policies and gates can hold a pull request when a dependency change trips a rule, and its SBOM and dependency scanning show new packages. Start with a free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how a dependency change is held at the pull request.
Quick check
What does the resolved field show?
Where the package was fetched from: a tarball URL for registry packages, or a git URL with a commit for git dependencies.
Why not read package.json only?
It lists direct dependencies. The lockfile shows every package that will install, including transitive ones.
Sources
Last reviewed: 19 October 2026.
