Difference between tilde(~) and caret(^) in package.json

When working on a Node.js project we always had a file named package.json. This package.json is the core of a Node.js project. It keeps track of important metadata, dependencies, scripts, and other functional attributes related to the project.

When installing any dependencies in any Node project, the package.json keeps the name of the package as a key in the dependencies or devDependencies section along with a value which is a number preceded by a caret (^) or tilde (~) symbol. The number denotes the version of the package that we installed and the symbols are useful when updating our dependencies.

In this article, we’ll get an overview of Semantic Versioning or SemVer and then differentiate between using tilde(~) and caret (^) in our package.json file.

If you want to learn how to publish your own NPM Package, read our guide to building and publishing an NPM Package here.

NPM Semantic Versioning (SemVer)

Semantic Versioning used by many Open Source projects is a popular versioning scheme that lays down some rules and regulations on how to assign and increment the version number of packages. This system uses version numbers to show what changes have been made to the code and how significant those changes are from one version to the next.

Under this scheme, a version number of the form MAJOR.MINOR.PATCH increases the

Major version when there are changes that leads to APIs incompatible with previous versions
Minor version when new features are added having backward compatibility
Patch version when bug fixes are done without hampering backward compatibility

Suppose a version number is 3.2.4

4 represents patch release i.e. the package has gone through bug fixes in a backward-compatible manner.
2 represents a minor release i.e. new features have been added to the package with backward compatibility.
3 represents a major release i.e. there are major changes in the code and might not be backward compatible.

Using a tilde (~) in an NPM package.json

Using a tilde (~) before the version number of the dependency package means that we will accept only further patch releases from the version specified but will not receive any major or minor release if we were to install or update our dependency package.

Example: Using tilde (~) to update Express

Assume we have the express.js package installed in your project. At the time of writing, version 4.18.2 is the latest stable version while we have version 4.17.0 installed in your project. Our dependencies in package.json might look something like this.

"dependencies": {
    "express": "~4.17.0"
},

If we try to update our npm package, the latest package won’t be installed but only further patch releases for 4.17.0 will be installed if available because we had used tilde (~) while specifying our dependency.

Using a caret (^) in an NPM package.json

Using a caret (^) before the version number of the dependency package means that we can accept both patch and minor releases from the version specified but will not receive any major release if we were to install or update our dependency package.

Example 1: Using caret (^) to update Axios

Let’s assume we have Axios installed in our system. Now again, at the time of writing version 1.3.4 is the latest version while we have version 1.2.0 installed in our node project. Our package.json must look something like this

"dependencies": {
    "axios": "^1.2.0"
},

If we update our package, we will find that the package has been updated to 1.3.4 or whatever the latest version is whose major version number is 1.

Example 2: Using caret (^) to update loadash

We can take another example where we have the loadash package version 3.9.3 installed in our node project. The current version of loadash is 4.17.21. Our package.json looks something like this

"dependencies": {
    "loadash": "^3.9.3"
},

What would happen if we try to update?

The last minor and patch release of major version 3 gets installed which is 3.10.2 but not major version 4 if try to update our dependency.

Conclusion

Semantic Version is a popular version scheme to help developers from dependency hell. Using tilde (~) and caret (^) while mentioning the package version number in package.json, developers can save themselves from breaking their code to some extent while updating installed node packages.

Wondering what to read next?, read our Beginner’s Guide to Node Package Manager.