When an npm update changes your lockfile, breaks a peer dependency, fails in continuous integration, or introduces an audit warning, the fastest fix is usually a repeatable investigation rather than another install command. This checklist explains how package.json, package-lock.json, npm commands, peer dependencies, overrides, and audit results fit together so you can diagnose the change, test a safe resolution, and review the result before merging.
Overview
npm dependency problems usually come from a mismatch between declared intent, resolved versions, the local environment, and the installation command being used. Treat these as separate layers:
| Item | Purpose | What to inspect |
|---|---|---|
package.json | Declares direct dependencies, scripts, engines, and project metadata. | Version ranges, dependency groups, peer dependency declarations, and package-manager settings. |
package-lock.json | Records the resolved dependency tree and package metadata for reproducible installs. | Unexpected version changes, transitive packages, integrity data, lockfile format, and large unrelated diffs. |
npm install | Installs packages and may update the lockfile when the manifest or resolution changes. | Whether the command was run with the intended Node.js and npm versions. |
npm ci | Performs a clean install from the lockfile in environments such as CI. | Whether the lockfile matches package.json and whether required flags are configured. |
peerDependencies | States which host package versions a package expects to work with. | Conflicting ranges, duplicate host versions, and whether the application supplies the host. |
overrides | Requests a specific dependency version or dependency relationship in the installed tree. | Scope, compatibility, and whether the override addresses a temporary or permanent constraint. |
| Audit commands | Report known security advisories affecting installed packages. | Which package is affected, the dependency path, severity, and available remediation. |
The lockfile is not a generic cache. It is part of the project’s installation contract, so review it as code. At the same time, do not assume that every lockfile difference is harmful: a deliberate direct dependency update can legitimately change several transitive packages.
Checklist by scenario
When npm install changes the lockfile
- Check the working tree before installing. Record whether both
package.jsonandpackage-lock.jsonare already modified. - Confirm the Node.js and npm versions used locally. Compare them with the versions specified by the project or CI environment.
- Run
git diff -- package.json package-lock.jsonand identify the first intentional change. Do not review only the end of a large generated diff. - Use
npm lsto inspect the installed tree. For a particular package, usenpm explain <package-name>to find why it is present. - Separate direct changes from transitive changes. A package may move because its parent package changed its range, because a new compatible release was selected, or because npm resolved a conflict differently.
- Run the project’s tests, build, lint, and type checks before deciding whether the lockfile update is acceptable.
When you see an npm peer-dependency error
- Read the complete error, including the package requesting the peer and the version currently installed.
- Inspect the relevant tree with
npm ls <host-package>andnpm explain <plugin-package>. - Check whether the peer is supplied by the application or by another package. For example, a framework plugin may expect the application to install a compatible framework version.
- Choose a resolution deliberately: upgrade the host, downgrade the plugin, select a compatible plugin release, or replace the package.
- Use
overridesonly when the forced version is known to be compatible and the reason can be documented. An override can silence a resolution problem while leaving a runtime incompatibility. - Treat
--legacy-peer-depsas a temporary diagnostic or compatibility measure, not as proof that the dependency relationship is safe. If it is required in CI, document why and keep the setting consistent across environments.
When CI fails at npm ci
- Look for a manifest-lockfile mismatch.
npm ciis intentionally strict and commonly fails when the lockfile does not describe the currentpackage.json. - Check whether local installation used flags that affect dependency resolution, such as peer-dependency or omit settings. Reproduce the same configuration through the project’s committed npm configuration or CI environment.
- Remove local installation artifacts only after capturing useful evidence, then retry from a clean checkout or clean workspace.
- Verify registry configuration, authentication, network access, and platform-specific optional dependencies separately from dependency resolution.
- Use the same package manager and lockfile type throughout the workflow. Do not alternate casually between npm, another package manager, and different lockfiles.
When an audit reports a vulnerability
- Run
npm auditand read the dependency path instead of applying an automatic fix immediately. - Determine whether the affected package is direct or transitive, and whether it is used in production, development, build tooling, or an optional path.
- Check the suggested remediation. A non-breaking update may be suitable; a forced major update requires application testing and a review of release notes.
- Use
npm audit fixonly with a review plan. Inspect the resulting manifest and lockfile diff, then run tests and build verification. - For a vulnerable transitive package without an available upstream fix, consider a documented override, a parent-package upgrade, temporary risk acceptance, or replacement. Record the decision rather than hiding the warning.
What to double-check
Before merging a dependency update, confirm the resolution is reproducible. A practical sequence is:
- Capture the baseline. Note the current Node.js and npm versions, test status, lockfile state, and the reason for the update.
- Make one focused change. Avoid combining a framework migration, formatting-only changes, and unrelated dependency upgrades in one diff.
- Regenerate intentionally. Update the direct dependency with the project’s supported command, then inspect both manifest and lockfile changes.
- Inspect the tree. Use
npm lsfor duplicates and invalid relationships, andnpm explainto trace why a package exists. - Test the behavior that matters. Run unit tests, integration tests, type checks, linting, builds, and a smoke test of the affected feature.
- Test the clean path. In a disposable environment, run the same clean-install command used by CI. A successful local install with an existing
node_modulesdirectory is not enough. - Review security output. Check audit results after the final tree is installed, not only before the update.
Also check the project’s engines field and documented runtime support. Node.js and npm behavior can vary across versions, and lockfile formats are tied to npm generations. When a project changes its supported runtime, regenerate and validate the lockfile under that runtime rather than assuming an older local install is representative.
For deployment workflows, keep dependency installation separate from application debugging. If a package update affects HTTP clients, configuration, or generated API code, use a focused diagnostic workflow such as the HTTP Request Debugging Guide or the OpenAPI Validation and Documentation Workflow to verify the resulting behavior.
Common mistakes
- Deleting the lockfile as a first response. This discards useful resolution history and can introduce many unrelated updates. Preserve it, inspect it, and regenerate only when there is a clear reason.
- Using
npm installin CI. This can resolve newer versions allowed by ranges. Use the project’s clean, lockfile-based command when reproducibility is required. - Committing only
package.json. A changed manifest without its intended lockfile update can make local and CI installations disagree. - Accepting
--forceor--legacy-peer-depswithout investigation. These options may move the failure from installation time to runtime or production. - Treating every audit warning as an emergency upgrade. First identify the path, affected usage, available fix, and potential breaking changes.
- Mixing package managers. Multiple lockfiles create ambiguity about which dependency graph is authoritative.
- Ignoring optional and platform-specific packages. A clean install on one operating system does not guarantee identical native-module behavior elsewhere.
- Reviewing only the final test result. A passing test suite does not explain an unexplained lockfile change, an unrecorded override, or a CI configuration difference.
When to revisit
Use this checklist before every dependency update, after a Node.js or npm migration, when CI begins failing at installation, when a lockfile conflict appears, and whenever an audit result changes. Revisit the project’s documented commands before seasonal planning or release cycles, especially if the team has changed its supported runtime, registry configuration, or package manager.
For a pull request, confirm that:
- the reason for the update and the intended direct packages are stated;
- Node.js, npm, and package-manager expectations are clear;
- the lockfile diff contains no unexplained changes;
- peer conflicts, overrides, and install flags are documented;
- clean installation, tests, builds, and relevant smoke checks pass;
- audit findings have a recorded resolution or risk decision; and
- the final diff is limited enough for another reviewer to understand.
Finally, keep this workflow beside your other operational checks. Dependency changes can affect deployment manifests, generated documentation, and runtime configuration; related reviews such as the Kubernetes Configuration Validation Guide and Markdown Linting and Documentation Workflow can help verify those downstream changes. Repeating the same evidence-based process is safer than relying on whichever npm command happened to work last time.