standard-version: automatic version bumps and CHANGELOG generation from Conventional Commits

What standard-version replaces, and who it is for

The package describes itself in package.json as a "replacement for `npm version` with automatic CHANGELOG generation". That is the whole scope. If you already run `npm version minor` and then hand-write a changelog entry, standard-version is the tool that removes the second step and the manual choice of the first.

It is built for teams that write Conventional Commits. The README's "How It Works" section states the contract plainly: follow the Conventional Commits Specification in your repository, then run `standard-version` when you are ready to release. The semver level is inferred from the commit types rather than typed by a human, which is the actual value proposition. A `feat:` commit and a `fix:` commit produce different version numbers without anyone deciding.

The audience is narrower than the topic list suggests. The README says the default configuration assumes a NodeJS project, which is why `package.json` and `manifest.json` appear as the standard `packageFiles`. Non-JavaScript projects are supported through `npx` and explicit configuration, but they are the exception the documentation calls out rather than the default path. If your repository has no version field in a JSON file and no git tags yet, you are doing more setup than a Node user would.

The release pipeline: packageFiles, bumpFiles and updaters

standard-version splits version handling into three concepts, and the distinction matters once you leave a plain npm package. `packageFiles` are files where a version can be read from and written to. `bumpFiles` are files where a version should be written but not read from, with `package-lock.json` and `npm-shrinkwrap.json` given as examples. `updaters` are the modules that do the reading and writing. In most projects `packageFiles` is a subset of `bumpFiles`, and the README notes you may never need to touch these options.

The run itself is a fixed sequence. The tool retrieves the current version by looking at `packageFiles`, falling back to the last git tag. It bumps the version in `bumpFiles` based on your commits. It generates a changelog using conventional-changelog under the hood. It creates a commit containing the bumped files and the updated CHANGELOG. Then it creates a tag with the new version number.

Two details are easy to miss. The changelog preset is conventionalcommits as of 6.0.0, and the README says that preset follows the conventionalcommits.org specification and is configurable through the conventional-changelog-config-spec. The second is the URL formats: `commitUrlFormat`, `compareUrlFormat` and `issueUrlFormat` are the dials you change when you are on GitLab rather than GitHub. Those three keys are the difference between a changelog full of working links and one full of dead ones.

Installing standard-version and cutting a first release

There are three install routes in the README, and they are not equivalent. The recommended one is a local dev dependency, which keeps the tool version pinned with the repository so other developers can cut releases without a global install. Add it with npm, then wire an npm run script into package.json.

npm i --save-dev standard-version

{
  "scripts": {
    "release": "standard-version"
  }
}

After that, `npm run release` stands in for `npm version`. The global route is `npm i -g standard-version`, which puts the binary on your PATH and lets you use it in any repository without adding a dev dependency to each one. The third route is `npx standard-version`, which the README says works as of [email protected] and is especially useful in non-JavaScript projects because it does not require a package.json.

For a first release, the README gives a dedicated flag. Running it tags the release without bumping the version in the bump files.

npm run release -- --first-release

After that you push the git tag and publish. For ordinary releases you drop the flag and run `npm run release` or `standard-version` depending on how you installed it. The README's note on nested configuration is worth remembering: pass nested options with dot notation, for example `--skip.changelog`, rather than defining them in package.json.

Where standard-version is the wrong tool

The largest limitation is stated at the top of the README: standard-version is deprecated. The maintainer recommends release-please for GitHub users, and points to the commit-and-tag-version fork for people who cannot use GitHub Actions or need to stay on standard-version for another reason. A deprecation notice is not a bug, but it changes the adoption calculation. New work on the package is not promised.

The second limitation is the commit history itself. Every version decision and every changelog line is derived from commit messages. If your team does not write conventional commits consistently, the tool will produce a version number that does not match the change, or a changelog with entries filed under the wrong heading. The README frames this as an assumption, not a fallback: "As long as your git commit messages are conventional and accurate, you no longer need to specify the semver type." That conditional is doing real work. Squash merges that flatten a feature branch into one message, or a merge commit policy that hides the individual messages, will change the output in ways the README does not walk through.

The third limitation is the local, imperative model. standard-version runs on a developer machine or a CI job that you write yourself, and it commits and tags in your working repository. That is a different shape from a hosted release bot that opens a pull request and waits for review. If your process requires a human to approve the version number before the tag exists, the standard-version flow assumes you inspect the commit and the CHANGELOG after the fact. The README does not document a rollback path for a tag that was created with the wrong number.

release-please and commit-and-tag-version: two different exits

The README names two alternatives and they solve the problem in opposite ways. release-please is a GitHub-oriented tool: it works through GitHub Actions and, in the usual flow, proposes the release as a pull request rather than committing straight to your branch. The version number and changelog become reviewable artifacts before the tag exists. That is the maintainer's recommendation for GitHub users, and it is the right comparison point for anyone who wants approval in the loop.

commit-and-tag-version is a fork of standard-version, described in the README for people who cannot use GitHub Actions or need to keep the standard-version behaviour. Because it is a fork, the mental model carries over: same local, imperative run, same packageFiles and bumpFiles configuration, same conventional-changelog machinery. The practical difference for an existing user is the migration cost, which is lower than moving to a pull-request-based bot. If your release runs in GitLab CI or a self-hosted runner, the fork keeps the shape you already have.

The choice is therefore not about features. It is about whether the version decision should be proposed and reviewed, or executed and inspected. standard-version and its fork execute. release-please proposes. Pick the one that matches where your review already happens.

Licence, maintenance and the upgrade question

standard-version is licensed under ISC, a permissive licence that the repository records in LICENSE.txt and in the package.json `license` field. ISC is short and permissive, closer to MIT than to a copyleft licence, but this is a description of what the repository states, not legal advice. If you redistribute the package or bundle it into a product, read LICENSE.txt and get your own counsel.

The maintenance picture is mixed and the README is the reason. The last push to the repository was on 2026-07-16, but the most recent release listed is v9.5.0 from 2022-05-15, and the README opens with a deprecation notice. A repository can receive commits while the published package stays still. Treat the deprecation statement as the governing fact rather than the push date.

Upgrade cost is mostly configuration drift. The changelog preset changed to conventionalcommits in 6.0.0, and the README directs you to the conventional-changelog-config-spec for the available options, so a configuration written against an older preset may need its keys checked. The package.json declares `"engines": { "node": ">=10" }`, which is the floor for running it. Moving to commit-and-tag-version means replacing the dependency and the `release` script; the `.versionrc` file and the packageFiles and bumpFiles settings should carry across because the fork keeps the same concepts.

Editorial conclusion

Adopt standard-version only if you are already running it, or you cannot use GitHub Actions and want the commit-and-tag-version fork instead. Do not start a new GitHub-hosted project on it: the README itself recommends release-please and calls standard-version deprecated. Before you commit either way, check the --first-release behaviour on a scratch repository, confirm whether your release flow needs --skip.tag or --skip.changelog, and read the conventional-changelog-config-spec for the exact keys your .versionrc will accept.

Frequently asked questions

Official sources

1. conventional-changelog/standard-version on GitHub
2. Issues
3. License: ISC
4. README
5. Releases