How to Use This Tool
Compare two versions, sort a list, or check what a range permits. The text-sorted column is there so you can see what a naive comparison would have told you.
Why string sorting fails
Comparing versions as text compares one character at a time, so 1.0.10 comes before
1.0.9 — the character "1" is less than "9" and the comparison stops there. Anywhere
versions are sorted as strings, the tenth patch release will appear older than the ninth.
Correct comparison reads major, minor and patch as numbers and compares them in order. Only if all three are equal does anything else matter.
Pre-release versions sort before the release
This is the part that surprises people, and it is deliberate: 1.0.0-alpha is
older than 1.0.0. A pre-release is a version on the way to the release, so it must
sort before it.
Within pre-releases, identifiers are compared piece by piece: numeric parts numerically, text parts
alphabetically, and a numeric identifier always sorts lower than a text one. That gives the ordering
people expect — alpha, then beta, then rc — only because those words happen to be in
alphabetical order. 1.0.0-preview would sort after 1.0.0-beta and before
1.0.0-rc, which is alphabetical and not chronological.
Caret and tilde
^1.2.3— anything from 1.2.3 up to but not including 2.0.0. Minor and patch updates are accepted automatically.~1.2.3— anything from 1.2.3 up to but not including 1.3.0. Patch updates only.1.2.3— exactly that version, nothing else.
There is an exception worth knowing: for versions below 1.0.0 the caret is much stricter, because
pre-1.0 releases are not expected to be stable. ^0.2.3 allows only up to 0.3.0, behaving
like a tilde. That is why a dependency at 0.x can break on what looks like a minor bump.
What ranges cannot protect you from
Semantic versioning is a promise made by the author, not a property the tooling verifies. Nothing stops a minor release from containing a breaking change, whether by accident or because the author disagreed about what counts as breaking.
So a caret range means "I trust this maintainer to classify their own changes correctly", which is a reasonable default and not a guarantee. A lockfile is what actually makes builds reproducible; the range only decides what a fresh install or an update is allowed to pick.
