Introduction

If you want to update the version in package.json automatically, the safest default is npm version. It understands semantic versioning, updates the related npm metadata files, and can also create the release commit and tag for you. That is better than editing JSON manually because it keeps the version bump tied to the package manager's own workflow.

Use npm version for normal release bumps

For patch, minor, major, and prerelease increments, npm version is the standard tool.

npm version patch
npm version minor
npm version major

You can also set an explicit version:

npm version 2.4.0

And if you want a prerelease:

npm version prerelease --preid=rc

In current npm documentation, npm version updates package.json, package-lock.json, and npm-shrinkwrap.json when applicable. In a Git repository, it also creates the version commit and tag by default.

Control whether Git commit and tag are created

Sometimes you want npm to update the version files but let CI or release tooling handle commits and tags later. In that case, disable the Git side effects.

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

That is useful in automated pipelines where another step is responsible for composing the final release commit. It also helps when you want to inspect generated artifacts before tagging anything.

If you do skip the built-in Git behavior, make the follow-up steps explicit:

git add package.json package-lock.json
git commit -m "chore: bump version"
git tag v$(node -p "require('./package.json').version")

The key point is consistency. Either let npm own the release commit and tag, or disable that behavior and own it fully in your pipeline.

Use lifecycle scripts around the version bump

One of the most practical features of npm version is that it runs lifecycle scripts. That lets you enforce tests before the bump, generate files during the bump, and push tags afterward.

1{
2  "scripts": {
3    "preversion": "npm test",
4    "version": "npm run build && git add -A dist",
5    "postversion": "git push && git push --tags"
6  }
7}

This is a solid pattern because it turns versioning into a repeatable release step rather than a manual edit followed by a pile of human memory.

CI workflows usually separate bumping from publishing

In CI, many teams run the bump with --no-git-tag-version, inspect the resulting version, build artifacts, and publish only if the pipeline passes. That keeps failed builds from creating misleading tags.

npm version minor --no-git-tag-version
NEW_VERSION=$(node -p "require('./package.json').version")
echo "Preparing release $NEW_VERSION"

You can also use from-git when Git tags are already your source of truth:

npm version from-git

That approach works well when release orchestration happens outside npm and the repository tags define the version.

Avoid manual JSON editing unless you really need it

You can technically edit package.json directly, or use generic JSON tools, but that is usually the wrong default for release automation. Direct editing does not automatically follow npm's version rules and can leave the surrounding workflow inconsistent.

The more your release process depends on predictable tags, lockfile updates, and script hooks, the more valuable npm version becomes.

Common Pitfalls

The most common mistake is bumping the version in a dirty working tree. npm can refuse the operation or capture unrelated changes in the release commit.

Another issue is assuming --no-git-tag-version means "skip only the tag." Current npm docs describe that flag as disabling the version commit and tag behavior, so do not assume a commit will still appear.

Teams also forget that prerelease bumps follow semver rules. If you use prerelease versions, decide whether the next step should be another prerelease or a final release.

Finally, do not forget the lockfile. One reason to prefer npm version is that it updates the version metadata consistently across npm-managed files.

Summary

• Use npm version as the default way to bump package.json automatically.
• It handles semantic version increments and updates npm-managed version files.
• By default it also creates a Git version commit and tag in a repository.
• Use --no-git-tag-version when CI should control commit and tag creation itself.
• Add preversion, version, and postversion scripts to make the release flow repeatable.