Understanding library versions
You may have noticed that library versions on NPM, JSR and in your deno.json (or package.json) have numbers attached to them.
For example, at the time of writing, the Simple Data Analysis library is at version 5.0.5. This is called semantic versioning, or SemVer for short.
When library maintainers update these numbers, there is (usually 😅) a good reason why — and in this lesson, I’m going to explain what that reason is!
Major, minor, and patch
Major
The first number indicates major versions. When this number changes, it means that breaking changes were introduced. If you are using an older version and update the library, your code will probably need to be updated too. Some classes, methods, functions, and others may have been changed or even removed.
So if you plan on updating to a major version, always plan some extra time to adjust your project. And always ask yourself if it’s actually worth it!
For example, if you are using simple-data-analysis@5.0.0 and there is a new version simple-data-analysis@6.0.0, check the release notes to weigh the pros and cons of updating your project with it.
There’s also an extra thing to know about major versions: when it’s a v0.x.x version, it usually means that the library is not ready for production. The maintainers will probably introduce a lot of breaking changes before it reaches v1.0.0, as they’re trying to figure out the best way to build everything. A lot of bugs are to be expected too.
Minor
Minor versions are usually used to notify about new features.
For example, if you are using simple-data-analysis@5.0.0 and there’s a new simple-data-analysis@5.1.0, it probably means that there is a new class, new methods, or new functions available. The old ones are still there and should still work as before.
It’s much safer to update to a minor version, since you shouldn’t have to recode parts of your project. But this is code, and maintainers are humans (for now 🤖), so there are always some surprises! 😬
Patch
Patch versions are usually used to fix bugs and improve things under the hood. They usually don’t bring anything new to the table — just make the library work better.
Patch versions are the safest versions to update to. You shouldn’t have to recode anything in your project when updating to a patch version.
Other versions
Some maintainers also like to publish alpha, beta, and rc (release candidate) versions.
These versions are available to anyone to use while the code changes — but at their own risk. A lot of bugs and breaking changes are to be expected.
^ and ~
Because it could be annoying to update libraries all the time for minor and patch versions, some projects prefix the library versions in the deno.json or package.json with ^ or ~.
These symbols define a range of acceptable versions for a library.
^ (Caret)
The ^ means that a project should stick to a major version, but can use any minor and patch version.
For example, simple-data-analysis@^5.0.0 means that the project is allowed to use the latest version of v5.x.x. So simple-data-analysis@5.1.0 and simple-data-analysis@5.1.1 would be acceptable.
~ (Tilde)
The ~ is stricter, meaning that the project should stick to a major and minor version, but can use any patch version.
For example, simple-data-analysis@~5.1.0 means that the project is allowed to use the latest version of v5.1.x, like simple-data-analysis@5.1.1.
Updating dependencies
You can follow maintainers and projects on GitHub to stay up to date with your favorite libraries (check the GitHub lesson), but you can also use Deno and NPM directly to check if some of your libraries are outdated.
Deno
With Deno, you can run deno outdated in your terminal. Deno will automatically check JSR and NPM and let you know what’s available. You can then update the libraries of your choice.
There are also different options available with this command.
Always double-check that your project is running as expected after updating and that the correct versions are written down in your deno.json.
NPM
NPM does the same thing with the npm outdated command. To update libraries, you can use npm update.
Again, always double-check that your project is running as expected after updating and that the correct versions are written down in your package.json.
Conclusion
SemVer is important to understand the potential consequences of updating a library. But remember that it’s a convention — nothing forces anyone to follow it.
In fact, some big open-source projects don’t follow SemVer, like… TypeScript! The team instead follows a calendar-based release schedule and sticks to it. Last time I checked, they released a new minor version every three months and a new major version when the minor version exceeds 9. But they do a lot of extra work to avoid breaking changes, so updating is often seamless for coders like us!