Semantic Versioning (SemVer)
The strict, three-part numbering system that tells developers exactly how risky an update is.
What is SemVer?
Semantic Versioning (SemVer) is a universal specification for version numbers, strictly enforced by npm and the node-semver engine.
Instead of arbitrary numbers like v1.2 or v2026, SemVer forces a rigid three-part format: MAJOR.MINOR.PATCH (for example, 1.4.2).
Each segment communicates the exact nature of the changes inside the release, allowing developers to know instantly if upgrading will break their code.
Why does it matter?
Before SemVer, updating a dependency was a gamble. A jump from 1.1 to 1.2 might include tiny bug fixes, or it might completely rewrite the API and crash your app.
SemVer creates a binding contract between the package author and the user. By following the rules, tools like npm can automatically pull down safe bug fixes while preventing breaking updates from destroying your production builds.
How it works
The rules for MAJOR.MINOR.PATCH are absolute:
1. **MAJOR** version when you make incompatible API changes (breaks existing code).
2. **MINOR** version when you add functionality in a backward-compatible manner.
3. **PATCH** version when you make backward-compatible bug fixes.
You can also append pre-release tags (like -beta.1) or build metadata (like +exp.sha.5114f85) to the end. A pre-release tag tells npm the version is unstable, giving it a lower precedence than the standard release.
SemVer Interactive Lab
Try adjusting the version components in the interactive lab below to see exactly how npm classifies the release.
Bump Version
Evaluated SemVer
"Stable release"
Remember this
- MAJOR breaks the API, MINOR adds features, PATCH fixes bugs.
- Major version 0 (e.g., 0.x.x) means the API is unstable and can break at any time.
- Pre-release tags like
-alpha.1indicate the version is unstable and has lower precedence.
Done with this concept?
Mark it complete to track your progress. No login needed.