Update about-semantic-versioning.mdx to clarify version resolution and pre-releases #1655
Conversation
| <Note> | ||
|
|
||
| **Note:** When using version ranges in your `package.json`, npm resolves to the **highest available version** that satisfies the specified constraints. This behavior ensures that consumers automatically receive the most recent compatible stable release, as long as the changes remain within the defined semver range. Pre-release versions (e.g., `1.2.0-beta.1`) are ignored unless explicitly requested or allowed via specific configuration. | ||
|
|
There was a problem hiding this comment.
I believe that if your range includes a prerelease then new prereleases will be included.
There was a problem hiding this comment.
Thanks for your input! You're absolutely right that when the version range explicitly includes a prerelease version — like >11.0.0-pre.0 — then further prereleases will be considered as valid candidates.
My contribution was intended to reflect the default behavior when the version range does not explicitly include a prerelease version — for example, using ^1.0.0 or ~2.2.0. In those cases, even if a prerelease version exists within the semantic range (like 1.1.0-beta.0), npm install will not install it unless:
- the prerelease is explicitly included in the version range, or
- the version is installed directly via
npm install some-lib@1.1.0-beta.0.
This behavior has even led to some confusion in the community, as discussed in npm/cli#7851, where users expected >x.y.z-beta to include later prereleases — but npm does not currently resolve those by default.
This distinction between stable and prerelease resolution isn't always obvious, so I thought it would be helpful to clarify. Happy to refine the wording further if needed!
This pull request adds a note to the "About semantic versioning" guide to clarify how npm resolves versions within defined ranges in
package.json. It specifies that npm installs the highest compatible stable version and ignores pre-releases like1.2.0-beta.1unless explicitly allowed by configuration.The goal is to help developers better understand version behavior and prevent unexpected installations when using semver constraints.
References
None