Picture of Michael Lee

npm pre version 1.0 caret rules

Written on November 1, 2020

In my article about the tilde ~ and the caret ~ in package.json files used to manage project dependencies with npm, I mentioned that the caret symbol is used to grab either the latest minor and patch versions of a package.

What I didn’t know until today is that, this rule only applies to versions that have reached at least version 1.0.0.

A reader had reached out on Twitter and mentioned this,

Screenshot of tweet about pre 1.0 caret rule question

Not knowing the answer right away, I dug around npm’s documentation regarding how they use semvar versioning and found this interesting bit in the caret section.

Allows changes that do not modify the left-most non-zero digit in the [major, minor, patch] tuple. In other words, this allows patch and minor updates for versions 1.0.0 and above, patch updates for versions 0.X >=0.1.0, and no updates for versions 0.0.X.

Many authors treat a 0.x version as if the x were the major “breaking-change” indicator.

What this means is the caret ~ tells npm to only grab the latest package based on where the non-zero number is in a package’s version number.

So, if the package you’re trying to grab has the latest version as 0.11.0 and in your pacakge.json file it is set as ^0.10.5, npm will only grab any patch level updates to the pacakge and not the 0.11.0 version.

This makes sense as indicated in the quote above, some developers until they reach 1.0 like to treat the—major.minor.patch—minor version of the application as a “major” change. This could lead to a breaking change for a project, thus, npm errs on the cautious side and grabs only the patch versions.

Stay in touch

Thanks for reading this article. I'd love to stay in touch and share more tips on programming and side projects with you. Sign up and I'll send you my articles straight to your email, you'll also get a free copy of the light themed version of my Git cheat sheet.
Git cheat sheet preview image