Npm Semantic Versioning

Summary: in this tutorial, you will learn about the semantic versioning to specify the version for your package or to install a specified version of an external package.

Introduction to semantic versioning in npm

To make the JavaScript ecosystem more reliable and secure, you should update the version number in the package.json file that follows the semantic versioning specification:

major.minor.patchCode language: JavaScript (javascript)

For example:

4.17.1Code language: JavaScript (javascript)

In this version:

• The major version is 4.
• The minor version is 17.
• The patch is 1.

For a specified version, you should increment:

• The major version when you make changes that are not compatible with the previous version.
• The minor version when you add a backward-compatible feature with the previous version.
• The path version when you make bug fixes that are backward-compatible with the previous version.

If you develop a new package, the starting version should be 1.0.0.

When you make one or more bug fixes that are backward-compatible with the version 1.0.0, you increase the third digit 1.0.1.

When you introduce new backward-compatible features, you increment the middle digit and reset the third digit to zero like 1.1.0

However, when you make changes that are not backward-compatible with the previous version, you increase the first digit and reset the middle and last digits to zero e.g., 2.0.0

npm semantic versioning

The following explains how to calculate the semantic versioning.

1) Carat (a.k.a hat) symbol ^

To include any version that is greater than a particular version in the same major range, you use the carat symbol (^):

^1.10.1
Code language: JavaScript (javascript)

2) Tilde symbol ~

To include any version that is greater than a particular version in the same minor range, you use the tilde symbol (~):

~1.5.12
Code language: JavaScript (javascript)

3) Comparison operators

To specify a range of stable versions, you use one of the comparison operators >, <, =, >=, <= :

>1.5Code language: JavaScript (javascript)

Or you can use the hyphen (-) to specify a range:

1.0.0 - 1.5.0
Code language: JavaScript (javascript)

Note that there are spaces on both sides of the hyphen.

4) Prerelease versions

To include a prerelease version e.g., alpha and beta, you use the prerelease tag:

1.0.0-alpha.1
Code language: JavaScript (javascript)

To specify a range of prerelease version, you use the comparison like > with a prerelease tag:

>=1.0.0-alpha.0 <1.0.5
Code language: JavaScript (javascript)

5) Include multiple sets of versions

To include multiple sets of versions, you use || to combine. For example:

 <1.2.0 || > 1.2.3Code language: JavaScript (javascript)

6) Use the x symbol

Use the x symbol to specify any version. For example, 1.x matches any versions with the major version 1 like 1.0.0, 1.1.2, 1.10.20, etc.

Install a package with a specific version

To install a package you use the npm install command:

npm install <package_name>Code language: JavaScript (javascript)

To install a package of specified version, you use the @ sign:

npm install <package_name>@versionCode language: JavaScript (javascript)

The following example installs the express package with the version 4.x:

npm install express@4.xCode language: JavaScript (javascript)

It will install the express package with the highest version of 4.x e.g., 4.17.1

Summary

• npm uses the semantic versioning specification with the format major.minor.patch.