npm-version

Check current version

$ npm version

$ npm version minor

$ npm version [version]

$ npm version patch --no-git-tag-version

$ npm version major [[-m|--message]] "[Upgrade to %s for reasons]"

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git] [options]

<newversion>
    A specific version string to set (e.g., 1.2.3).

major | minor | patch | premajor | preminor | prepatch | prerelease
    Increments the package version according to semantic versioning rules.

from-git
    Reads the new version from the latest Git tag.

--force
    Forces the version bump, even if the Git working directory is not clean or the version already exists.

--allow-same-version
    Allows the command to succeed even if the new version is identical to the current one.

--no-git-tag-version
    Prevents npm version from creating a Git commit and tag.

--no-commit-hooks
    Bypasses Git commit hooks (e.g., pre-commit) when creating the version commit.

--no-push
    Prevents the newly created commit and tag from being pushed to the remote Git repository.

--tag-version-prefix <prefix>
    Specifies a prefix for the Git tag (default is v, so tags are like v1.0.0).

--preid <preid>
    Identifier for a pre-release version (e.g., alpha, beta, rc) when using pre-release increments.

--message <message>, -m <message>
    Custom commit message for the version commit. The default is v%s where %s is the new version.

The npm version command is a powerful utility for managing the version of a Node.js package, as defined in its package.json file. It allows developers to increment the package's version according to semantic versioning rules (major, minor, patch, pre-release) or set a specific version string.

Beyond simply updating the package.json, npm version deeply integrates with Git. By default, it performs a sequence of actions: it updates the version in package.json, creates a Git commit for this change, and then creates a Git tag with the format v (e.g., v1.0.0). Optionally, it can also push these changes, including the new commit and tag, to the remote Git repository.

This automated workflow streamlines the release process, ensuring consistency between the package's declared version and its corresponding Git tag, which is crucial for reproducible builds and clear release history. It also supports custom commit messages and allows for hooks to run scripts at different stages of the versioning process.

The command requires a Git repository to be initialized and accessible for its default Git integration features. It modifies package.json and package-lock.json directly. For best practice, ensure your working directory is clean (no uncommitted changes) before running npm version, unless explicitly using --force.

By default, npm version performs a Git commit and creates a Git tag. This behavior ensures that your package's version in package.json is always aligned with a corresponding Git tag, facilitating release management. Options like --no-git-tag-version, --no-commit-hooks, and --no-push provide fine-grained control over this integration.

npm version executes specific lifecycle scripts defined in package.json around the versioning process:
preversion: Runs before the version is bumped.
version: Runs after the version is bumped, but before the commit.
postversion: Runs after the commit and tag are created.
These scripts are useful for automating tasks like building assets, running tests, or performing cleanup operations during a release.

The npm version command has been a core part of the npm CLI since its early days, evolving to support modern semantic versioning practices and tighter integration with Git workflows. Its functionality has remained consistently focused on automating release versioning and Git tagging.

npm publish(1), git(1), semver(7)