Generate a lockfile on a clean machine, review what it resolved, commit it on its own, and switch CI to a frozen install. Without a lockfile, each install resolves versions from the ranges in the manifest, so two builds of the same commit can differ. The first lockfile is a baseline, so treat it as a review event.
Why it is a problem
The npm documentation says package-lock.json describes the exact tree that was generated so subsequent installs produce identical trees regardless of intermediate dependency updates, and that it is meant to be committed. The Cargo Book makes the same argument for Cargo.lock: builds made on different days could get different commits, and reproducible builds are the goal. A repo without that file has no record of what was actually shipped.
First-day plan
- Check it is really missing. Look in ignore files. Some repos hide the lockfile by accident.
- Ask why. There may be a reason, such as a library workflow. Ask the owner before changing anything.
- Use a clean checkout. Install from the manifest on a clean machine or container so local leftovers do not leak in.
- Run the install to generate the file. Use the standard command for your ecosystem.
- Review the result. Skim the resolved versions of direct dependencies. Run an audit and note what is flagged.
- Commit the lockfile alone, in a pull request that changes nothing else, with a description of what you did.
- Switch CI to the frozen install, such as npm ci for Node, which errors if the lock and manifest disagree.
Handle the first audit calmly
Expect findings. The lockfile did not create them, it exposed them. Do not fix everything in the same pull request. Record the findings, open tickets, and fix in small changes. If you want to know which matter, check what is reachable and exposed before ranking them.
Set the rule going forward
| Rule | Why |
|---|---|
| Lockfile changes ship with manifest changes | Keeps the pair in sync |
| CI uses frozen install | Drift fails loudly |
| Lockfile diffs get reviewed | New transitive packages are visible |
| Updates happen on a schedule | Versions move on purpose |
See npm ci failures from lockfile drift and our guide to onboarding repositories to scanning in waves.
Where Safeguard fits
Safeguard can do the inventory and watching for you. Its SBOM and dependency scanning lists what a repository actually pulls in, reachability analysis helps separate reachable findings from noise, and policies can gate a pull request. You can try a free scan on a repository to see the output.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how a baseline scan is followed by ongoing checks as new advisories appear.
Quick check
Is it ever right not to commit a lockfile?
Some library projects choose that. Follow your tool's docs and the owner's reasoning, and write the decision down.
Should I upgrade everything while I am at it?
No. Create the baseline first, then update in small, reviewed steps.
Sources
Last reviewed: 19 October 2026.
