How to Update npm Packages to their Latest Version

In any NodeJS project, you’ll want to update your package dependencies often. Luckily, the process is simple and can be done in mere minutes. Of course, you want to verify any updates with some QA and hopefully some automated tests (a test framework or CI tool can be helpful).

The npm update command allows you to update any out-of-date packages, according to your package.json versions. This is the default way to update packages with npm.

One built-in way to check which packages are outdated is to run the npm outdated command.

Another way, which I prefer, is to use the npm-check-updates (ncu) module. This package allows you to easily upgrade your package.json dependencies to the latest versions of modules regardless of any version constraints in those files. Then with the npm install or npm update commands you can upgrade the installed packages.

---

In the rest of this article, we’ll take a look at the various NodeJS tools to update npm packages to their latest version, with or without semantic versioning constraints. Specifically, we’ll cover:

Semantic Versioning Overview | Getting Started + Sample NodeJS Project | Detecting Updates
Strict vs. Non-Strict Versioned Updates

Jump ahead using the links above or read on to explore the world of npm package updating!

Any npm or bower packages can use semantic versioning (semver) as specified on the semver.org website. This means that a package version can consist of three components:

1. MAJOR version for when there are incompatible API changes
2. MINOR version for when functionality is added in a backwards compatible manner
3. PATCH version for when backwards compatible bug fixes are done

Node-semver is the package that parses the semvers and also understands some additional semver syntax, such as: basic ranges, tilde ranges, pre-release tags, caret ranges, hyphen ranges, and x ranges.

As a user of NodeJS packages, you can specify which kinds of updates your app can accept in the package.json file. For example, if you were starting with a package version 1.0.4, this is how you could specify the allowed update version ranges in three basic ways:

• To Allow Patch Releases: 1.0 or 1.0.x or ~1.0.4
• To Allow Minor Releases: 1 or 1.x or ^1.0.4
• To Allow Major Releases: * or x

More fine-grained version ranges are also available if you use the additional semver syntax mentioned above.

Now we can install the ncu tool globally, by typing the following:

npm install -g npm-check-updates

You might first need root user permissions though; if so, type “sudo” in front of that command:

sudo npm install -g npm-check-updates

Let’s take a look at the ncu help syntax:

$ ncu --help

Usage: ncu [options] [filter]
[filter] is a list or regex of package names to check (all others will be ignored).

Options:
-h, --help                   output usage information
-V, --version                output the version number
-d, --dev                    check only devDependencies
-e, --error-level         set the error-level.
                                1: exits with error code 0 if no errors occur.
                                2: exits with error code 0 if no packages need
                                updating (useful for continuous integration). Default is 1.
-g, --global                 check global packages instead of in the current project
-j, --jsonAll                output new package file instead of human-readable message
--jsonUpgraded               output upgraded dependencies in json
-l, --loglevel            what level of logs to report: silent, error, warn,
                                info, verbose, silly (default: warn)
-m, --packageManager   npm (default) or bower
-o, --optional               check only optionalDependencies
--packageData                include stringified package file (use stdin instead)
--packageFile      package file location (default: ./package.json)
-p, --prod                   check only dependencies (not devDependencies)
-r, --registry          specify third-party npm registry
-s, --silent                 dont output anything (--loglevel silent)
-t, --greatest               find the highest versions available instead of the
                                latest stable versions
-u, --upgrade                overwrite package file
-a, --upgradeAll             include even those dependencies whose latest version
                                satisfies the declared semver dependency

Let’s create a sample NodeJS project called “foo,” which we will let depend upon an older “express” and “request” package version, to show how to upgrade packages using the NodeJS install, update, and ncu commands:

mkdir foo
cd foo
npm init
[answer npm init questions]
npm install --save express@3.1.x request@1.x

Now our package.json will look something like this:

{
  "name": "foo",
  "version": "1.0.0",
  "description": "foo",
  "main": "index.js",
  "scripts": {
    "test": "test"
  },
  "keywords": [
    "foo"
  ],
  "author": "none",
  "license": "ISC",
  "dependencies": {
    "express": "^3.1.2",
    "request": "^1.9.9"
  }
}

We see how npm installed the older versions of these two packages from their highest allowed and available packaged version and updated the package.json file.

To see which packages have available updates, we can either use the ncu tool or the npm outdated command.

Detecting Updates with npm

If we wanted to check for packages that have updates, you can use the npm outdated command:

$ npm outdated
Package  Current  Wanted  Latest  Location
express    3.1.2  3.21.2  4.13.3  express
request    1.9.9   1.9.9  2.67.0  request

We see that the “request” package version is in line with what we wanted (as stated by our semver during install), but that there is a new major version available. For the “express” package, we see that both the wanted and latest versions have newer versions available.

Detecting Updates with ncu

Using the ncu tool we can also detect which packages have newer versions:

$ ncu
express  ^3.1.2  ->  ^4.13.3 
 request  ^1.9.9  ->  ^2.67.0

We see that there are major updates for both packages available.

We can either allow for strict versioned updates (strictly within our package.json semver constraints) or non-strict versioned updates (to update regardless of our semver constraints).

Strict Versioned Updates Using npm

Let’s use the npm update command to allow for strict versioned updates:

$ npm update

Now let’s have a look at npm outdated again:

$ npm outdated
Package  Current  Wanted  Latest  Location
express   3.21.2  3.21.2  4.13.3  express
request    1.9.9   1.9.9  2.67.0  request

Nice, npm update did what we asked of it and no more!

Non-Strict Versioned Updates Using ncu

For non-strict versioned updates, there are several command line options we can use with ncu.

ncu –upgrade [package]

To upgrade the “request” package to its newest major version, we could do the following:

$ ncu --upgrade request
request  ^1.9.9  ->  ^2.67.0

This will update the package.json semver for the “request” package:

  "dependencies": {
    "express": "^3.1.2",
    "request": "^2.67.0"
  }

Please note that the ncu tool does maintain your existing semantic versioning policies (e.g., “allow only minor upgrades,” in our case), when updating the package.json file. Therefore, the major version of the “request” package was increased, but the policy of only allowing minor upgrades upon a npm update is still in effect.

Now we need to install the updated package version using npm install:

npm install

Let’s check the installed “request” package version:

$ npm list request
foo@1.0.0 /home/user/foo
|--- request@2.67.0

ncu –upgrade

To update all of our package dependencies in package.json (including our “express” package), we would do the following:

ncu --upgrade
npm install

ncu –upgradeAll

The ncu tool can install newer package versions according the package.json semver constraints, but does not update those newer version in the package.json file.

If you want to enforce writing those newly installed package versions to your package.json, you can use the –upgradeAll option. Though not necessary, this functionality is there if you want it.

To enforce overwriting your package.json package versions to their latest (semver-allowed), specific version number, type:

ncu --upgradeAll
npm install

Filtering with ncu

We could also upgrade packages matching some regular expression syntax.

For example, this would match and upgrade all packages starting with “gulp-“:

ncu --upgrade /^gulp-/

To check only the “dependencies” packages, and not also the “devDependencies” packages, do the following:

$ ncu -p

This can be useful in cases where you want more developer environment stability.

Using bower.json

To use the bower.json file with ncu, you specify that option on the command line:

$ ncu -m bower

NodeJS has great tooling for flexible package management and dependency versioning. Be sure to have a look at the npm documentation to learn more about npm package management and best practices.