Know the difference between tilde and caret in package.json

Most of us might have wondered what does the tilde (~) and caret (^) prefixing the version number of the “dependencies” in your package.json file mean. Well, it is important to know the difference between tilde and caret in package.json as the wrong usage can even break your project.

Understanding the usage of tilde (~) and caret(^) in package.json

The tilde (~) and caret(^) have a very specific use in the package.json file and they both convey different messages. To understand it better, let’s take a look at an example of dependencies in the package.json file.

"dependencies": {
  "next": "^11.0.0",

  "react": "~17.0.2",
  "react-dom": "~17.0.2"
}

In the example above, we can notice that the “next” package has a caret (^) prefixing its version number, while on the other hand, the other two packages have a tilde(~) prefixing its version number.

We can also notice that the version numbers usually have 3 integers(can be alphanumeric too) which are separated by a dot in between two integers. They are in the format of Major.Minor.Patch.For e.g 17.0.2 , which means that the Major version is 17, Minor version is 0, and the Patch version is 2.

NPM Package version numbers are in the format of Major.Minor.Patch

A Patch version usually refers to very minor updates like a security patch, bug fix, etc. Usually upgrading from one patch to another is not harmful. For e.g upgrading from 17.0. 2 to 17.0. 3.

A Minor version upgrade usually refers to the introduction of new features and /or upgrades and are not just patch fixes or security fixes. The upgraded version will still be backward compatible and will not break your functionality. For e.g upgrading from 17. 0.2 to 17. 1.0

A Major version upgrade would mean that a major refactoring of the code has been done and there might be breaking changes that have been introduced. For e.g upgrading from 17.0.2 to 18.0.0

You can read more about the semantic version numbering at https://semver.org/ and at NPM Docs. Well, now that we understand the version’s numbering, let’s take a look at what does tilde (~) and caret (^) symbols signify.

What is tilde in package json?

A tilde (~) as a prefix to the version number in package JSON means that whenever an update is run or whenever the packages are installed, it would look for the latest patch version available in the npm registry and install it. In other words, if say the version was mentioned as “~17.0. 2 “, it can go ahead and upgrade to 17.0. x version where x is the highest available patch version in that Major.Minor.Patch combination. This means that the max it can go until is “17.0. 9 ” (if 9 was the last patch released). A tilde basically asks the npm to install only the latest patch version of the package and ignore any minor or major upgrades.

With Tilde ( ~ ) as the prefix, npm would update the package to the latest patch version available.

What is Caret in package.json?

On the other hand, A Caret (^) as a prefix to the version number in package.json means that whenever an update is run or the packages are installed, look for the latest minor and its latest patch version available in the npm registry and install it. This means that if the version in package.json was mentioned as “^17. 0. 2 “, it can update until version “17. x. x “, where x is the highest minor and patch version available. So assume if react has released a version 17.1.1 recently and I run the npm update command, npm would go ahead and upgrade the package from version “17.0.2” to “17.1.1”. Now assume if React released version 18.0.1 and I run the update, even then I would still get only version 17.1.1 (if that was the latest version before releasing version 18.0.1)

With Caret (^) as prefix, npm would update the package to the latest minor and its latest patch version.

Please note that with Caret as prefix, even though it updates to the latest minor and its latest patch version , the Major version number remains the same. Most of the times the package would be backwards compatible too.

The core difference between tilde and caret in package.json

Well, to summarize, we can say that the core difference between tilde and caret in package.json is mainly to do with instructing the npm on which latest version of the package should be installed. A tilde ( ~ ) would mean that the latest Patch version of a specific Major.Minor combination should be installed e.g 17.0. 2.

A caret ( ^ ) would mean that the latest Minor and its latest patch version should be installed e.g 17. 9. 9. In both cases, the Major version remains the same e.g 17.0.2 and 17.9.9 both have 17 as the Major version number.

If you want to install a specific version of npm package, you can do that too by removing both the tilde and caret signs and by just keeping the exact package version number like “react” : “17.0.2”

Tool to check the semantic version number Range in package.json

You can also use Semantic version calculator from official NPMJs website at https://semver.npmjs.com/ . Here you can try out the tilde and caret prefixes to check which versions of package would be covered with it. You can even select the package of your choice and try out the prefix.

I hope you are clear with the difference between tilde and caret in package.json. As I mentioned earlier, it is important that we understand the difference between tilde and Caret in package.json. Wrong usage of the tilde or caret can cause breakages in your app. If for some reason you installed the wrong version of package, you can go ahead and remove the npm package from project and install the desired version.

The post Know the difference between tilde and caret in package.json first appeared on MoreOnFew.