Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 36 ยท Installing and Versions

Semantic Versioning (semver)

Understand semantic versioning, what MAJOR, MINOR and PATCH promise, how pre-release tags and build metadata work, and how to compare and sort versions correctly with code.

Every package on the registry carries a version like 4.17.21. Those three numbers are not arbitrary: by convention they follow semantic versioning ("semver"), a promise about how much can break between releases. Package managers lean on that promise when they decide which updates are safe to install automatically.

The three numbers

A version has the form MAJOR.MINOR.PATCH:

  • MAJOR: incompatible changes. Upgrading may require changes in your code.
  • MINOR: new features that keep existing behavior working.
  • PATCH: bug fixes with no new features and no breaking change.

So 2.4.1 -> 2.4.2 should be safe, 2.4.1 -> 2.5.0 adds things, and 2.4.1 -> 3.0.0 may break you. Numbers increase independently and never have leading zeros. When MINOR goes up, PATCH resets to 0; when MAJOR goes up, both reset.

What each number promises

MAJOR 2.x to 3.0: may break your code
MINOR 2.4 to 2.5: new features, still compatible
PATCH 2.4.1 to 2.4.2: bug fixes only

Package managers use this promise to pick safe updates.

1 / 2

Versions below 1.0.0

Major version 0 means "anything may change". For 0.y.z ranges, a minor bump (0.3.0 -> 0.4.0) is treated as potentially breaking by the tools, which you will see in Version Ranges. Reaching 1.0.0 signals a stable public API.

Pre-release versions and build metadata

A hyphen adds a pre-release tag: 2.0.0-beta.1, 2.0.0-rc.2, 1.5.0-alpha. A pre-release sorts before the release it leads up to: 2.0.0-beta.1 < 2.0.0. A plus sign adds build metadata, such as 1.0.0+20260101, which is ignored when comparing.

Pre-release identifiers are compared piece by piece (separated by dots): numeric pieces numerically, others alphabetically, and numeric pieces rank below text. Package managers will never install a pre-release for a plain range like ^2.0.0 unless the range itself mentions one.

Parsing and comparing

Because 1.10.0 is newer than 1.9.0, versions must be compared as numbers. Here is a compact, correct parser and comparator you can experiment with. (The real library is the npm package semver, which every manager uses; this is a stand-in with the same ordering rules.)

Node.js Parse and compare versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Observe that 2.0.0-beta.11 sorts after 2.0.0-beta.2 because the pieces are numeric, and that build metadata never changes the order.

Bumping versions

Release tools apply the rules mechanically. Here is a bump function and how npm version relates to it:

Node.js Bump a version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

On the command line, npm version patch|minor|major edits package.json, and in a git repository also commits and tags (v1.4.3). That belongs to the Publishing chapter.

Semver is a promise, not a guarantee

Maintainers are human. A "patch" release occasionally breaks something, and projects with enormous APIs sometimes ship breaking changes in minor versions. That is why lockfiles and test suites matter even when everyone follows the rules. Some projects use other schemes entirely, such as calendar versioning (2026.3.1); registries accept any valid x.y.z.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which bump signals an incompatible change?

    A MAJOR increase means existing code may need changes.
  2. 2. Which is the newest version?

    Compare numerically: 1.10.0 is above 1.9.x.
  3. 3. How does 2.0.0-beta.1 compare with 2.0.0?

    A pre-release precedes the final version it leads to.
  4. 4. What happens to MINOR and PATCH when MAJOR is bumped?

    1.5.3 becomes 2.0.0 on a major bump.

Summary

  • Versions are MAJOR.MINOR.PATCH: breaking, feature, fix.
  • Pre-releases (-beta.1) sort before their release; build metadata (+x) is ignored.
  • Compare numerically, never as text.
  • 0.y.z versions make no stability promise.
  • Semver is a convention; keep a lockfile and tests.

Next: Version Ranges: Caret, Tilde and More