SemVer Calculator — Free Online Tool

What is Semantic Versioning?

Semantic Versioning (SemVer) is a versioning specification that uses a three-number format: MAJOR.MINOR.PATCH (e.g., 2.4.1). It provides a standard way to communicate the nature of changes in each release, helping developers understand what to expect when they update a dependency.

The SemVer specification (semver.org) defines clear rules: increment MAJOR for breaking changes, MINOR for new backwards-compatible features, and PATCH for backwards-compatible bug fixes.

When to Bump Each Version Part

• MAJOR (breaking change): Removed a public API method, changed function signatures, deprecated and removed old behavior, changed authentication flow.
• MINOR (new feature): Added a new endpoint, added optional parameters to existing functions, added new configuration options.
• PATCH (bug fix): Fixed a crash, corrected incorrect behavior, performance improvement with no API change, documentation fix.

npm Version Range Syntax

• ^1.2.3 — Compatible with 1.2.3. Allows MINOR and PATCH updates (>=1.2.3 <2.0.0)
• ~1.2.3 — Approximately equivalent. Allows only PATCH updates (>=1.2.3 <1.3.0)
• >=1.2.3 <2.0.0 — Explicit range, very clear intent
• 1.x — Any version with major version 1
• * — Any version (dangerous for production)
• 1.2.3 — Exact version only (no updates)

Semantic Versioning in Practice: Beyond the Theory

Semantic Versioning (SemVer) provides a clear contract between library authors and consumers about what changes to expect in each release. However, real-world versioning decisions are often more nuanced than the simple MAJOR.MINOR.PATCH formula suggests.

When to Bump Each Version Number

• MAJOR (breaking changes): Removing a public API, changing a function signature, renaming exported modules, dropping support for a runtime version (Node.js 16 → 18 minimum), or changing default behavior that existing users rely on.
• MINOR (new features, backwards-compatible): Adding new functions, endpoints, or options. Adding optional parameters to existing functions. Deprecating (but not removing) existing APIs. Adding new event types or enum values.
• PATCH (bug fixes only): Fixing incorrect behavior, security patches, performance improvements that don't change the API, documentation corrections, and dependency updates that don't affect the public API.

Version Range Strategies for package.json

• ^1.2.3 (caret — default for npm): Allows MINOR and PATCH updates: ≥1.2.3 <2.0.0. Best for most dependencies — trusts that the library follows SemVer correctly. This is what npm install uses by default.
• ~1.2.3 (tilde): Allows only PATCH updates: ≥1.2.3 <1.3.0. More conservative — use for dependencies with a history of breaking changes in minor versions.
• 1.2.3 (exact): Locks to exactly this version. Most conservative — use for critical dependencies where any change is risky (database drivers, auth libraries). Consider using a lockfile instead.

Pre-release Versions and Build Metadata

SemVer supports pre-release identifiers (1.0.0-alpha.1, 2.0.0-beta.3, 1.0.0-rc.1) for versions that may not satisfy the stability guarantees of the normal version. Pre-release versions have lower precedence than the release version: 1.0.0-alpha < 1.0.0. Build metadata (1.0.0+20260314) is ignored in version precedence comparisons but useful for tracking build information.

Frequently Asked Questions about Semantic Versioning

What is the difference between ^1.0.0 and ~1.0.0 in npm?

The caret (^) allows compatible updates within the same major version: ^1.0.0 permits any version >=1.0.0 and <2.0.0, allowing both minor and patch updates. The tilde (~) is more restrictive: ~1.0.0 allows only patch updates, matching >=1.0.0 and <1.1.0. npm uses caret (^) as the default. Use tilde when you need tighter control over what versions are installed.

When should I increment the major version number?

Increment major (e.g., 1.x.x → 2.0.0) only for breaking changes that are not backwards-compatible with the previous version. This includes: removing or renaming a public API method, changing a function's parameter signature, dropping support for a previously supported runtime or environment, or changing default behavior that breaks existing integrations. Non-breaking additions always go to minor, and bug fixes always go to patch.

What does a version number starting with 0 mean?

Versions starting with 0 (e.g., 0.x.x) signal that the software is in initial development and the public API is not yet stable. Under SemVer, anything may change at any time during 0.x development — including breaking changes with minor version bumps (0.1.0 → 0.2.0). Only increment to 1.0.0 when you are ready to commit to a stable, documented public API that you will maintain backwards-compatibility for.

How do I release a prerelease version using SemVer?

Append a prerelease identifier after a hyphen: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1. Prerelease versions have lower precedence than the release: 1.0.0-alpha < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. In npm, publish prereleases with npm publish --tag next so they are not installed by default. Caret and tilde range selectors do not match prerelease versions automatically.

Related Developer Tools

• Git Command Finder — find the exact Git command for tagging, branching, and releasing
• Docker Compose Generator — generate production-ready docker-compose.yml configurations
• .ENV File Inspector — validate environment files and detect exposed secrets
• JWT Decoder & Inspector — decode JWT tokens and inspect claims securely in browser
• View all free developer tools