How to Update Packages and Bump Versions Using npm CLI Commands

In the previous tutorial we showed you how to either uninstall a package from your development environment as well as how to get your package unpublished from the registry using npm uninstall and npm unpublish respectively.

In this tutorial we will examine how you can update a package as well as how you can bump a package version.

Npm update

The npm update command helps you to update a package.

Synopsis

npm update [-g] [<pkg>...]
aliases: up, upgrade

Description

This command updates all the package listed to their latest version (specified by the tag config), respecting the semver.

It also installs missing packages. As with all commands that installs packages, using the -dev flag will cause the devDependencies to be processed as well.

If you also specify the -g flag, this command updates the globally installed packages.

If you do not specify a package name, then all the packages in the specified location (global or local) will be updated.

As of [email protected], the npm update only inspects top-level packages. Prior versions of npm recursively inspects all dependencies. If you want to get the old behavior, you have to use npm ?depth 9999 update.

As of [email protected], the npm update changes the package.json to save the new version as the minimum required dependency. If you want the old behavior, you have to use npm update ?no-save.

EXAMPLES

IMPORTANT VERSION NOTE: The examples below assume [email protected] or later. For older versions of npm, you have to specify --depth 0 to get the behavior described below.

For the examples below, assume that the current package is demoapp and it depends on dependencies, demodep1 (demodep2, .. etc.). The published versions of demodep1 are:

{
  "dist-tags": { "latest": "1.2.3" },
  "versions": [
    "1.2.3",
    "1.2.2",
    "1.2.1",
    "1.2.0",
    "1.1.1",
    "1.0.0",
    "0.4.1",
    "0.4.0",
    "0.2.0"
  ]
}

Caret Dependencies

If demoapp's package.json contains:

"dependencies": {
  "demodep1": "^1.1.1"
}

Then npm update will install [email protected], because 1.2.3 is latest and 1.2.3 satisfies ^1.1.1.

Tilde Dependencies

However, if demoapp's package.json contains:

"dependencies": {
  "dep1": "~1.1.0"
}

In this case, running npm update installs [email protected]. Even though the latest tag points to 1.2.2, this version does not satisfy ~1.1.0, which is equivalent to >=1.1.0 <1.2.0. So the highest-sorting version that satisfies ~1.1.0 is used, which is 1.1.1.

Caret Dependencies below 1.0.0

Suppose demoapp has a caret dependency on a version below 1.0.0, for example:

"dependencies": {
  "demodep1": "^0.2.0"
}

npm update will install [email protected], this is because there are no other versions which satisfy ^0.2.0.

If on the other hand, the dependencies were on ^0.4.0:

"dependencies": {
  "dep1": "^0.4.0"
}

Then npm update will install [email protected], this is because that is the highest-sorting version that satisfies ^0.4.0 (>= 0.4.0 <0.5.0)

Updating Globally-Installed Packages

npm update -g applies the update action to each globally installed package that is outdated -- that is, the package that has a version that is different from latest.

It should be noted that, if you upgrade a package to a version that is newer than latest, it will be downgraded.

npm-version

This command bumps a package version.

Synopsis

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]

'npm [-v | --version]' used to print npm version
'npm view <pkg> version' used to view a package's published version
'npm ls' used to inspect current package/dependency versions

Description

Running this in a package directory will bump the version and write the new data back to package.json, package-lock.json, and, npm-shrinkwrap.json if it is present.

The newversion argument has to be a valid semver string, it also has to be a valid second argument to semver.inc (one of patch, minor, major, prepatch, preminor, premajor, prerelease), or from-git. In the second case, the existing version is incremented by 1 in the specified field. from-git will attempt to read the latest git tag, and then use that as the new npm version.

If you run this command in a git repo, it also creates a version commit and tag. This behavior is controlled using the git-tag-version, and can be disabled on the command line when you run npm --no-git-tag-version version. This will fail if the working directory is not clean, unless you set the -f or -force flag.

If supply this command with -m or --message config option, npm uses it as a commit message when creating a version commit. In the case where the message config contains %s then that will be replaced with the resulting version number. For instance:

npm version patch -m

The command above will upgrade to %s.

If you set the sign-git-tag config, then the tag is signed using the -s flag to git. Note that you need have a default GPG key set up in your git config for this to work properly. For instance:

$ npm config set sign-git-tag true
$ npm version patch

You will need a passphrase to unlock the secret key for
user: "isaacs (http://blog.izs.me/) <[email protected]>"
2048-bit RSA key, ID 6C481CF6, created 2010-08-31

Enter passphrase:

If you have preversion, version, or postversion in the scripts property of the package.json, they are executed as part of running npm version.

This is the exact order of execution:

1. Check to ensure the git working directory is clean before you get started. Your scripts might add files to the commit in future steps. This step will be skipped if the --force flag is set.
2. Run the preversion script. These script has access to the old version in package.json. A typical use case would be running your full test suite before deploying. Any files you want added to the commit has to be explicitly added using git add.
3. Bump the version in package.json as requested (patch, minor, major, etc).
4. Run the version script. This script has access to the new version in package.json (so it can incorporate it into file headers in generated files for instance). Again, scripts have to explicitly add generated files to the commit using git add.
5. Commit and tag.
6. Run the postversion script. You should use it to clean up the file system or to automatically push the commit and/or tag.

Configuration

allow-same-version

• Default: false
• Type: Boolean

This configuration option prevents throwing an error when npm version is used to set the new version to the same value as the current version.

git-tag-version

• Default: true
• Type: Boolean

Commits and tags the version change.

commit-hooks

• Default: true
• Type: Boolean

Runs git commit hooks when committing the version change.

sign-git-tag

• Default: false
• Type: Boolean

Passes the -s flag to git to sign the tag.

It should be noted that you must have a default GPG key set up in your git config for this to work properly.

Previous: Npm-uninstall and npm-unpublish cli commands
Next: Npm-view and npm whoami