How to Safely Upgrade npm Dependencies and Keep Your Project Healthy

Core Goals

Improve maintainability and avoid conflicts with newly introduced packages.

Increase portability, making migration to newer npm or pnpm versions easier.

Boost reliability by receiving bug‑fixes from actively maintained dependencies.

Enhance security by staying within safe version ranges and addressing known vulnerabilities.

Process Methodology

Use professional assessment tools; manual "npm install @latest" treats dependencies as black boxes.

Prioritize core and security‑critical packages to keep effort predictable.

Read changelogs and evaluate impact before upgrading.

Conduct thorough regression testing.

Beyond testing, the person leading the upgrade must understand both the project and the packages being updated; otherwise the risk is high.

Tooling

Below examples use npm; pnpm and yarn have equivalent commands.

Outdated Dependencies (npm outdated)

The npm outdated command checks installed packages against the npm registry.

Package               Current   Wanted    Latest   Location
axios                 0.18.1    0.18.1    0.27.2   project-dir
log4js                2.11.0    2.11.0    6.5.2    project-dir
lru-cache             4.1.5     4.1.5     7.10.2   project-dir
socket.io             2.4.1     2.5.0     4.5.1    project-dir
vue                   2.6.14    2.6.14    3.2.37   project-dir
vue-lazyload          1.3.3     1.3.4     3.0.0-rc.2 project-dir
vue-loader            14.2.4    14.2.4    17.0.0   project-dir
vue-router            3.5.3     3.5.4     4.0.16   project-dir
vuex                  3.6.2     3.6.2     4.0.2    project-dir
webpack               3.12.0    3.12.0    5.73.0   project-dir

By default only direct dependencies are checked; use --all to include transitive ones, though a full lock‑file rebuild is often preferred for a thorough upgrade.

Update outdated packages with npm update (or the equivalent command in other managers). For major version jumps, specify the target version manually.

Risky Dependencies (npm audit)

The npm audit command sends the package-lock.json to the registry and returns a list of known vulnerabilities without needing a node_modules folder.

# Run npm install [email protected] to resolve 1 vulnerability
SEMVER WARNING: Recommended action is a potentially breaking change
┌───────────────┬──────────────────────────────────────────────────────────────┐
│ Critical      │ Prototype Pollution in swiper                                 │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Package       │ swiper                                                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Dependency of│ swiper                                                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ Path         │ swiper                                                         │
├───────────────┼──────────────────────────────────────────────────────────────┤
│ More info    │ https://github.com/advisories/GHSA-p3hc-fv2j-rp68               │
└───────────────┴──────────────────────────────────────────────────────────────┘
found 125 vulnerabilities (8 low, 66 moderate, 41 high, 10 critical) in 2502 scanned packages
  run `npm audit fix` to fix 15 of them.
  96 vulnerabilities require semver‑major dependency updates.
  14 vulnerabilities require manual review. See the full report for details.

If the registry returns a 404, it means the current registry does not support the audit endpoint; switch to an official registry.

While npm audit fix can address some issues, it is limited; upgrading root dependencies often resolves more indirect vulnerabilities.

Implicit Dependencies (npx depcheck)

The depcheck CLI helps locate Unused dependencies (declared but not used) and Phantom dependencies (used but not declared).

Depcheck is a filter, not a definitive source; it may miss special plugins.

Unused dependencies
 * clipboard
 * cross-env
 * firebase
 * proxy
 * route-cache
 * socket.io
Unused devDependencies
 * add-asset-html-webpack-plugin
 * commitizen
 * eslint
 * husky
 * jasmine
 * rimraf
 * stylelint
Missing dependencies
 * node-notifier: ./build/utils.js

Removing an unused package requires understanding its purpose and confirming with tools like grep.

Zombie Dependencies (npm install)

Zombie dependencies are still used but have been deprecated or archived, so they do not appear in outdated or audit lists, yet they may contain unfixed bugs.

No dedicated tool exists; watch the deprecation warnings during npm install.

Governance Recommendations

How to Read CHANGELOG

Look for CHANGELOG.md, History.md, GitHub releases, or official migration guides. If a package lacks a changelog, examine commit history.

Common keywords: BREAKING CHANGE , ! , Node.js .

Lock‑File Version Management

Including package-lock.json in version control ensures consistent dependencies across team members and CI, provides a lightweight backup of node_modules, makes dependency tree changes visible, and speeds up installations. Whether to commit the lock file depends on project needs.

Updating Hoisting

Over time, top‑level dependencies may lag behind transitive ones because npm’s hoisting algorithm minimizes changes. Even if direct dependencies are updated to the latest, indirect ones can stay outdated, causing divergence.

For severely stale projects, regenerate the lock file:

rm -rf package-lock.json node_modules
npm i

Consider switching to a package manager that avoids hoisting.

Organizing dependencies vs. devDependencies

dependencies are required at runtime, while devDependencies are for development tools. Keeping them separate allows npm install --production to skip dev tools, reducing install size. For production builds, npm prune --production can further trim the bundle. Do not misuse devDependencies for optional runtime packages; use optionalDependencies instead.

Conclusion

The article provides an overview of npm dependency governance, noting that tools like Yarn or pnpm have their own APIs. Managing dependencies well prevents code rot, even though many projects may never reach a point where dependency health becomes critical. Images illustrating the concepts: