Bumping Node.js dependencies

To bump the dependencies listed in package.json, I use ncu (npm-check-updates) or taze. Both check the npm registry for newer versions and rewrite package.json for you.

Why do we need a tool at all? npm update only moves within the version ranges already written in package.json. To go past those ranges, you’d edit version numbers by hand, package by package. These tools do that step for us.

Using ncu

Run it without installing anything:

npx npm-check-updates

This only prints what could be upgraded. Nothing is changed yet:

 astro          ^4.16.18  →  ^5.12.3
 tailwindcss     ^3.4.17  →  ^4.1.11

To actually write the new versions into package.json, add -u:

ncu -u

Then run npm install to install them. This is the pitfall that catches people: ncu -u only edits package.json. Until you run npm install, node_modules still has the old versions, and you’re testing against code you’re about to replace.

Staying within safe versions

By default, ncu upgrades the package to the latest version available.

Sometimes however I want to stay within the major version I’m on. For example I’m on 1.2 and I don’t want to jump to 2.3, I want to stick to 1.3 if it exists. Major bumps mean breaking changes, and I might not want to deal with them today.

We have the option to only upgrade to minor versions (ignoring major new versions, with breaking changes) with ncu --target minor (or ncu -t minor).

Upgrade only patch versions with ncu -t patch.

Patch releases should only contain bug fixes, so those are the safest bumps of all.

Using taze

I recently also found out about taze. A similar tool.

Use it as taze minor to bump to latest minor changes within the same major version.

Or if you prefer, taze major will check all changes and bump to the latest stable versions, including majors.

Patch updates, use taze patch.

Like ncu, taze first shows you the changes. Add -w to write them to package.json, then run npm install.

My advice

Don’t bump everything to latest blindly and move on. After a round of major upgrades, run the project and its tests before committing. When a major bump breaks something, the package changelog usually tells you what changed and what to update in your code.

If you’re not sure whether a change deserves a major, minor or patch bump in your own packages, I built a free semver advisor that helps with exactly this.