What is Semantic versioning?
© https://nodejs.org/en/

What is Semantic versioning?

Semantic versioning in Node.js

ByMario Kandut

honey pot logo

Europe’s developer-focused job platform

Let companies apply to you

Developer-focused, salary and tech stack upfront.

Just one profile, no job applications!

This article is based on Node v16.15.1 and NPM 8.11.0.

Semantic Versioning or semver is a core part in software development and has also become a core part of Node.js. Semver is already embedded in the way we publish and link packages together with NPM (check out Beginner's guide to NPM). Understanding semantic versioning plays a significant role in defining the way we build software.

What is Semver?

💰 The Pragmatic Programmer: journey to mastery. 💰 One of the best books in software development, sold over 200,000 times.

Semver is a specification outlining a method of encoding the change between releases of a "public interface", directly into the version string. A public interface could be basically anything an application programming interface (API), a command-line interface (CLI) or a graphical user interface (GUI). Anything that depends on having predictable interactions should be versioned semantically. Semver could even be extended to physical interfaces.

Semver is a scheme for interface versioning for the benefit of interface consumers. Thus, if a tool has multiple interfaces, e.g. an API and a CLI, these interfaces may evolve independent versioning. Although many applications do not consider their CLI to be part of their interface when versioning, a third-party may depend on specific CLI behaviour in the same way they might depend on an API.

In simple terms - "semver is a convention to provide a meaning to versions".

Semver Construction

A semver version is built from three numbers separated by dots .. These three numbers are referred to as major, minor and patch (reading left to right). The combination of these numbers represent an ordered version, where each of the three numbers are also ordered.

For example: Version 1.2.3 is ordered before Version 1.4.1 and Version 0.8.19 is ordered before 1.0.0.

Semver.org summarizes it like this:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards compatible manner, and
  • PATCH version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Semver Ranges in Node

Semver is important in the Node.js ecosystem, because it's built into the way that npm manages package dependencies.

All packages published to npm are assumed to follow semver semantics. Hence, it is used by nearly every package author to define what dependency versions the package is bundled with.

One major concept is Semver Ranges. This concept was inspired by Bundler (Ruby ecosystem), but for a ruby application semver ranges have greater implications than in the node.js ecosystem. In a Node.js project it is essential to have a pragmatic dependency management, since it is common to use several third-party packages.

Semver ranges are basically permitting newer version of packages to be installed automatically. Important bug fixes/patches can be received or distributed automatically, but major changes are forbidden to be installed.

Options for Semver Ranges

  • "*" The simplest semver range, which accepts any version. Default is the latest.
  • "2" or "2.x.x" Specify a specific version. "2" would cover all minor and patch versions.

You can specify version ranges with -, <, <=, > and >=. For example:

  • "1.2.3 - 2.3.4" is the same as ">=1.2.3 <=2.3.4"
  • ">=1.2.0 <1.3.0" is similar to "1.2.x"
  • "<1.0.0" only accepts versions in the range "0.x.x"

With the || operator you can also combine versions < 2.1 || > 1.9.

Shorthand Range Operators

Node.js has introduced shorthand ranges operators ~(tilde) and ^(caret).

~ (tilde) character defines a range of acceptable PATCH versions from the one specified up to, but not including, the next minor version. "~1.2.3" is similar to ">=1.2.3 <1.3.0". ^(caret) defines a range of acceptable PATCH and MINOR versions from the ones specified up to, but not including, the next version. So "^1.2.3" is similar to ">=1.2.3 <2.0.0".

TL;DR

  • Semver is a core part of Node.js and already integrated with NPM.
  • Semver ranges are basically permitting newer version of packages to be installed automatically.
  • There are several rules and operators to define semver ranges, and it is important to understand them.

Thanks for reading and if you have any questions, use the comment function or send me a message @mariokandut.

If you want to know more about Node, have a look at these Node Tutorials.

References (and Big thanks):

NodeSource, FlavioCopes, SemVer

More node articles:

Getting started with Webpack

How to list/debug npm packages?

How to specify a Node.js version

How to create a web server in Node.js

How to dynamically load ESM in CJS

How to convert a CJS module to an ESM

How to create a CJS module

How to stream to an HTTP response

How to handle binary data in Node.js?

How to use streams to ETL data?

How to connect streams with pipeline?

How to handle stream errors?

How to connect streams with pipe?

What Is a Node.js Stream?

Handling Errors in Node (asynchronous)

Handling Errors in Node.js (synchronous)

Introduction to errors in Node.js

Callback to promise-based functions

ETL: Load Data to Destination with Node.js

ETL: Transform Data with Node.js

ETL: Extract Data with Node.js

Event Emitters in Node.js

How to set up SSL locally with Node.js?

How to use async/await in Node.js

What is an API proxy?

How to make an API request in Node.js?

How does the Event Loop work in Node.js

How to wait for multiple Promises?

How to organize Node.js code

Understanding Promises in Node.js

How does the Node.js module system work?

Set up and test a .env file in Node

How to Use Environment Variables in Node

How to clean up node modules?

Restart a Node.js app automatically

How to update a Node dependency - NPM?

What are NPM scripts?

How to uninstall npm packages?

How to install npm packages?

How to create a package.json file?

What Is the Node.js ETL Pipeline?

What is data brokering in Node.js?

How to read and write JSON Files with Node.js?

What is package-lock.json?

How to install Node.js locally with nvm?

How to update Node.js?

How to check unused npm packages?

What is the Node.js fs module?

What is Semantic versioning?

The Basics of Package.json explained

How to patch an NPM dependency

What is NPM audit?

Beginner`s guide to NPM

Getting started with Node.js

Scroll to top ↑