What is the bower (and npm) version syntax?

by

In a nutshell, the syntax for Bower version numbers (and NPM’s) is called SemVer, which is short for ‘Semantic Versioning’. You can find documentation for the detailed syntax of SemVer as used in Bower and NPM on the API for the semver parser within Node/npm. You can learn more about the underlying spec (which does not mention ~ or other syntax details) at semver.org.

There’s a super-handy visual semver calculator you can play with, making all of this much easier to grok and test.

SemVer isn’t just a syntax! It has some pretty interesting things to say about the right ways to publish API’s, which will help to understand what the syntax means. Crucially:

Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version.

So, your specific question about ~ relates to that Major.Minor.Patch schema. (As does the related caret operator ^.) You can use ~ to narrow the range of versions you’re willing to accept to either:

  • subsequent patch-level changes to the same minor version (“bug fixes not affecting the API”), or:
  • subsequent minor-level changes to the same major version (“backwards compatible API additions/changes”)

For example: to indicate you’ll take any subsequent patch-level changes on the 1.2.x tree, starting with 1.2.0, but less than 1.3.0, you could use:

"angular": "~1.2"
  or:
"angular": "~1.2.0"

This also gets you the same results as using the .x syntax: 

"angular": "1.2.x"

But, you can use the tilde/~ syntax to be even more specific: if you’re only willing to accept patch-level changes starting with 1.2.4, but still less than 1.3.0, you’d use:

"angular": "~1.2.4"

Moving left, towards the major version, if you use…

"angular": "~1"

… it’s the same as…

"angular": "1.x"
  or:
"angular": "^1.0.0"

…and matches any minor- or patch-level changes above 1.0.0, and less than 2.0:

Note that last variation above: it’s called a ‘caret range’. The caret looks an awful lot like a >, so you’d be excused for thinking it means “any version greater than 1.0.0″. (I’ve certainly slipped on that.) Nope!

Caret ranges are basically used to say that you care only about the left-most significant digit – usually the major version – and that you’ll permit any minor- or patch-level changes that don’t affect that left-most digit. Yet, unlike a tilde range that specifies a major version, caret ranges let you specify a precise minor/patch starting point. So, while ^1.0.0 === ~1, a caret range such as ^1.2.3 lets you say you’ll take any changes >=1.2.3 && <2.0.0. You couldn’t do that with a tilde range.

That all seems confusing at first, when you look at it up-close. But zoom out for a sec, and think about it this way: the caret simply lets you say that you’re most concerned about whatever significant digit is left-most. The tilde lets you say you’re most concerned about whichever digit is right-most. The rest is detail.

It’s the expressive power of the tilde and the caret that explains why people use them much more than the simpler .x syntax: they simply let you do more. That’s why you’ll see the tilde used often even where .x would serve. As an example, see npm itself: its own package.json file includes lots of dependencies in ~2.4.0 format, rather than the 2.4.x format it could use. By sticking to ~, the syntax is consistent all the way down a list of 70+ versioned dependencies, regardless of which beginning patch number is acceptable.

Anyway, there’s still more to SemVer, but I won’t try to detail it all here. Check it out on the node semver package’s readme. And be sure to use the semantic versioning calculator while you’re practicing and trying to get your head around how SemVer works.

RE: Non-Consecutive Version Numbers: OP’s final question seems to be about specifying non-consecutive version numbers/ranges (if I have edited it fairly). Yes, you can do that, using the common double-pipe “or” operator: ||. Like so:

"angular": "1.2 <= 1.2.9 || >2.0.0"

More Related Contents:

  1. What’s the difference between tilde(~) and caret(^) in package.json?
  2. How to change bower’s default components folder?
  3. Bower: “command not found” after installation
  4. Node JS NPM modules installed but command not recognized
  5. bower command not found
  6. bower command not found windows
  7. What is the purpose of .bin folder in node_modules?
  8. npm install private github repositories by dependency in package.json
  9. npm ERR cb() never called
  10. Node – was compiled against a different Node.js version using NODE_MODULE_VERSION 51
  11. Why does “npm install” rewrite package-lock.json?
  12. node.js – Is there any proper way to parse JSON with large numbers? (long, bigint, int64)
  13. Expressjs raw body
  14. npm can’t find package.json
  15. Using the Underscore module with Node.js
  16. How to debug a socket hang up error in NodeJS?
  17. Module not found: Error can’t resolve ‘child_process’, how to fix?
  18. Listen additional port Microsoft Azure Nodejs
  19. What’s the difference between io.sockets.emit and broadcast?
  20. How can I publish an npm package with distribution files?
  21. how to use populate and aggregate in same statement?
  22. Automatically remove referencing objects on deletion in MongoDB
  23. What the scenario call fs.close is necessary
  24. Nodemailer/Gmail – What exactly is a refresh token and how do I get one?
  25. Node.js – Mongoose – Check if a collection exists
  26. What’s the difference between path.resolve and path.join?
  27. npm update check failed
  28. NodeJs Error – Failed to load gRPC binary module because it was not installed for the current system Expected directory?
  29. How to attach file to an email with nodemailer
  30. Mongoose overwrite the document rather that `$set` fields

Leave a Comment