Semantic Versioning

What is Semantic Versioning?

Semantic Versioning uses the format major.minor.patch:

• MAJOR version for incompatible API changes
• MINOR version for added backward-compatible functionality
• PATCH version for backward-compatible bug fixes

How npm Uses Semantic Versioning

In package.json, dependency ranges control allowed updates:

• Patch-level: "~1.2.3" or "1.2.x" → versions ≥1.2.3 <1.3.0
• Minor-level: "^1.2.3" or "1.x" → versions <2.0.0
• Major-level: "*" or "x" → any version

Example:

{
  "dependencies": {
    "foo": "^2.3.0",
    "bar": "~1.4.5"
  }
}

^2.3.0 allows 2.3.x, 2.4.x, but not 3.0.0. ~1.4.5 allows only 1.4.x updates.

npm Commands for Bumping Versions

npm version patch                    # e.g., 1.0.0 → 1.0.1
npm version minor                    # e.g., 1.0.1 → 1.1.0
npm version major                    # e.g., 1.1.0 → 2.0.0
npm version prerelease --preid=beta  # e.g., 1.2.3 → 1.2.4‑beta.0
npm publish --tag beta               # for publishing pre-release versions

This updates package.json, tags the commit, and increments the version appropriately.

Example Workflow

1. Start at version "1.0.0".
2. Fix a bug → npm version patch → "1.0.1".
3. Add a feature → npm version minor → "1.1.0".
4. Introduce a breaking change → npm version major → "2.0.0".

For pre‑releases:

npm version prerelease --preid=beta
# 1.1.0 → 1.1.1‑beta.0
npm publish --tag beta
npm install mypkg@beta

When ready for a stable release:

npm version minor   # e.g., 1.1.1‑beta.0 → 1.2.0
npm publish

Quick Reference Table

Version Bump	Meaning	npm Command
PATCH	Backward‑compatible bug fix	npm version patch
MINOR	Backward‑compatible feature add	npm version minor
MAJOR	Backward‑incompatible change	npm version major
Prerelease	Beta/alpha testing version	npm version prerelease

Conclusion

Semantic Versioning turns version numbers into a clear, machine‑readable contract that communicates the scope and impact of changes. By following its structure:

• Consumers gain confidence in safe upgrades,
• Developers enable automation in CI/CD pipelines,
• Teams benefit from predictable release management across projects.

When every component in your ecosystem adheres to MAJOR.MINOR.PATCH, version bumps reflect intentional decisions—not surprise breakages. Use tooling like npm version, commit‑driven conventions, and pre‑release tags to enforce this discipline. The result? A clearer development lifecycle, reliable dependency updates, and smoother collaboration across teams and services.