Update package.json dependencies to newer releases

Preview upgrades with npm-check-updates, revise dependency ranges in controlled batches, and validate the resulting lock file.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Best practices

Illustration of application modules working together

npm-check-updates can revise dependency ranges beyond their current limits. Run it without -u to inspect proposed changes, then update the declarations and install separately. “Latest” refers to the tool's selected target, normally the registry's latest dist-tag, rather than every numerically higher prerelease.

Preview, update, and test

Preserve the current working state and record a known-good commit before editing dependencies:

npx npm-check-updates
npx npm-check-updates -u
npm install
npm test

Also run the project's build and exercise its important user flows. Review both package.json and the lock file before committing.

npx can download and execute package code. Use the full package name npm-check-updates and, for repeatable team workflows, pin a reviewed tool version. npx ncu can resolve an unrelated package; the ncu executable is appropriate only when you know it comes from an installed npm-check-updates package.

Limit the upgrade scope

# Stay within patch or minor updates.
npx npm-check-updates --target patch -u
npx npm-check-updates --target minor -u

# Include only these packages.
npx npm-check-updates --filter 'react,vue' -u

# Exclude a package, or choose interactively.
npx npm-check-updates --reject webpack
npx npm-check-updates --interactive

Patch and minor targets reduce the size of the change; they do not guarantee compatibility. Review major upgrades individually, including migration guides, Node requirements, and plugin compatibility. Small, separate commits make regressions easier to isolate.

Compare with npm update

Operation	npm update	npm-check-updates -u
Uses current dependency ranges	Yes	Revises ranges to the selected target
Can cross a major version	If the existing range allows it	Can change the range to allow it
Edits direct dependency ranges	Normally unchanged; `--save` can update them	Yes
Installs packages	Yes	No; run the intended package manager afterward

Use npm outdated to inspect routine drift. An open range such as * or >=1.0.0 can already allow major upgrades, so npm update is not inherently restricted to patch and minor releases.

Recover and handle conflicts

If the upgrade breaks the project, inspect the diff and restore both declarations and lock file from the known-good baseline without overwriting unrelated work. Then use the lock-file installation mode, such as npm ci, to reproduce it.

For peer dependency conflicts, align the host package and its plugins or defer the incompatible upgrade. Avoid treating --legacy-peer-deps as a general repair for incompatible requirements.

In npm workspaces, preview with --workspaces. Current npm-check-updates releases include the root project by default; add --no-root to exclude it. Check the help for your pinned tool version rather than assuming the root is untouched. Add -u only after reviewing that scope. Alternatively, upgrade packages separately to keep each migration manageable.

References: npm update and npm-check-updates usage.