Mastering the semantic versioning syntax in package.json: A Beginner's Guide

Packages are the heart of the NodeJS echo system.

A package in NodeJS contains all the files required for a module. A module is a javascript library whose code can be reused in any javascript project. If you have worked on the NodeJS echo system, you might have already encountered a file named package.json.

The package.json file contains information related to the name, version, author, dependencies etc of the project. The dependencies are nothing but a list of packages on which the current project is dependent. This dependencies list contains the name: version pairs.

When a package is released, semantic versioning is followed to give the name for the release.

In this article, we are going to learn about the semantic versioning syntax in package.json

What is semantic versioning?

Semantic versioning is a universally agreed way to give naming for the release.

The syntax for the version name is:

MAJOR.MINOR.PATCH

E.g.

1.2.3

Here 1 is the MAJOR version, 2 is the MINOR version and 3 is the PATCH version.

How do we decide the determination of MAJOR, MINOR and PATCH?

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes (If there is a package, it must have public API means somehow the module should be accessible publicly)
2. MINOR version when you add functionality in a backwards-compatible manner
3. PATCH version when you make backwards-compatible bug fixes

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

This above rule is taken from its standard documentation.

Example of version syntax

A package.json's dependencies:

The above screenshot is from a package.json file.

In the above example, the package react is having 17 as the MAJOR version, 0 as the MINOR version and 1 as the PATCH version. Similarly, the styled-components package is having 5 as the MAJOR version, 3 as the MINOR version and 3 as the PATCH version.

When npm install or yarn install will be run, the react package will install its absolute version 17.0.1 and the styled-components package will install its absolute version 5.3.3 in node_modules.

Meaning of Tilde(~), Caret(^) and Asterisk(*) in version

Apart from MAJOR.MINOR.PATCH syntax, there are some other characters like Tilde (~), Caret(^) and Asterisk (*) used for in version value of some packages in dependencies in package.json.

For example:

"dependencies": {
	"package1": "~1.4.6",
	"package2": "^1.3.6",
	"package3": "*",
	"package4": "1.*",
	"package5": "1.3.*"
}

Tilde(~)

The Tilde character means that the MAJOR and MINOR version is locked and the PATCH version is variable.

~MAJOR.MINOR.PATCH means >= MAJOR.MINOR.PATCH but < MAJOR.MINOR+1.0

E.g.

~1.4.6 mean >=1.4.6 but <1.5.0. The version can be greater than or equal to 1.4.6 but less than 1.5.0.

Let’s say

"package1":"~1.4.6"

It means when we run npm install or yarn install, whatever latest version of package1 between 1.4.6 inclusive and 1.5.0 exclusive version is available, will be installed.

Caret(^)

The Caret character means that the MAJOR version is locked and the MINOR & PATCH versions are variable.

^MAJOR.MINOR.PATCH means >= MAJOR.MINOR.PATCH but < MAJOR+1.0.0

E.g.

~1.3.6 mean >=1.3.6 but <2.0.0. The version can be greater than or equal to 1.3.6 but less than 2.0.0.

Let's say

"package2":"^1.3.6"

It means when we run npm install or yarn install, whatever latest version of package1 between 1.3.6 inclusive and 2.0.0 exclusive version is available, will be installed.

Asterisk(*)

This character is used very less time nowadays. The asterisk (*) represents everything. The version meaning does change based on which version part it is being used.

If an asterisk(*) is used in the MAJOR version, then it means pretty much every version of that package is available.

* means >= 0.0.0

Let's say:

"package3": "*"

It means when we run npm install or yarn install, whatever latest version of package3 is available, will be installed.

If an asterisk(*) is used at MINOR version, it is greater than and equal to MAJOR.0.0 but less than MAJOR+1.0.0

MAJOR.* means >= MAJOR.0.0 but < MAJOR+1.0.0

E.g.

* means >=1.0.0 but <2.0.0

Similarly, If an asterisk(*) is used in the PATCH version, it is greater than and equal to MAJOR.MINOR.0 but less than MAJOR.MINOR+1.0

MAJOR.MINOR.* means >= MAJOR.MINOR.0 but <MAJOR.MINOR+1.0

E.g.

1.3.* means >=1.3.0 but <1.4.0

That's all.

I hope that you have liked the article. Keep coding and keep solving problems.