# npm version cheatsheet

## npm uses Semantic Versioning

npm uses [Semantic Versioning](https://semver.org). Given a version number `MAJOR.MINOR.PATCH`, increment the:

1. **MAJOR** version when you make incompatible API changes,
2. **MINOR** version when you add functionality in a backwards compatible manner, and
3. **PATCH** version when you make backwards compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the `MAJOR.MINOR.PATCH` format, e.g. `1.0.0-alpha`.

## Acceptable version ranges

To specify acceptable version ranges up to `1.0.4`, use the following syntax:

- **Patch releases:** `1.0` or `1.0.x` or `~1.0.4`
- **Minor releases:** `1` or `1.x` or `^1.0.4`
- **Major releases:** `*` or `x`

## npm version symbols

| Symbol   | Rule                                                           | Example                                   |
| -------- | -------------------------------------------------------------- | ----------------------------------------- |
| `^`      | accept updates to minor and patch releases only.               | `^0.13.0`: `0.13.1`, `0.14.0`             |
| `~`      | accept updates to patch releases only.                         | `~0.13.0`: `0.13.1` (not `0.14.0`)        |
| `>`      | accept updates to any version greater than the one specified.  | `>0.13.0`: `0.13.1`, `0.14.1`, `1.1.1`    |
| `<`      | accept updates to any version less than the one specified.     | `<3.0.0`: `2.0.0`, `2.9.0`                |
| `>=`     | accept any version greater than or equal to the one specified. | `>=3.0.0`: `3.0.0`, `4.1.0`               |
| `<=`     | accept any version less than or equal to the one specified.    | `<=3.0.0`: `3.0.0`, `2.9.0`               |
| `=`      | accept only the exact specified version.                       | `=3.0.0`: `3.0.0`, (not `3.0.1`)          |
| `-`      | accept a range of versions.                                    | `1.0.0 - 1.10.10`: `1.5.0` (not `1.11.0`) |
| `\|\|`   | accept a combination of versions.                              | `<2.1.0 \|\| >2.6.0`: `2.0.1`, `3.1.0`    |
| `x.x.x`  | accept only the specified version (no symbol).                 | `=3.0.0`: `3.0.0`, (not `3.0.1`)          |
| `latest` | always get latest version available.                           | `<package-name>@latest`                   |

## References

- [npm Docs: About semantic versioning](https://docs.npmjs.com/about-semantic-versioning)
- [npm Docs: npm-version](https://docs.npmjs.com/cli/v7/commands/npm-version)
- [The semantic versioner for npm](https://github.com/npm/node-semver?tab=readme-ov-file#ranges)
- [Flavio Copes: Semantic Versioning using npm](https://flaviocopes.com/npm-semantic-versioning/)

## Resources

- [npm semver calculator](https://semver.npmjs.com)