# @release-it/conventional-changelog

> Conventional changelog plugin for release-it

Latest version **12.0.2** (published 2026-09-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @release-it/conventional-changelog
pnpm add @release-it/conventional-changelog
yarn add @release-it/conventional-changelog
bun add @release-it/conventional-changelog
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 12.0.2 |
| Published | 2026-09-14 |
| First published | 2019-03-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | ^22.22.2 \|\| ^24.15.0 \|\| >=26.0.0 |
| Dependencies | 7 |
| Unpacked size | 46.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 178 |
| Author | Lars Kappert |
| Maintainers | webpro |
| Keywords | release, release-it, release-it-plugin, plugin, conventional, changelog, recommended, bump |

## Links

- npm: https://www.npmjs.com/package/@release-it/conventional-changelog
- Repository: https://github.com/release-it/conventional-changelog
- Homepage: https://github.com/release-it/conventional-changelog#readme
- Issues: https://github.com/release-it/conventional-changelog/issues
- npm.io page: https://npm.io/package/@release-it/conventional-changelog

## Dependencies (7)

- [semver](https://npm.io/package/semver.md) ^7.8.5
- [concat-stream](https://npm.io/package/concat-stream.md) ^2.0.0
- [conventional-changelog](https://npm.io/package/conventional-changelog.md) ^8.1.3
- [conventional-recommended-bump](https://npm.io/package/conventional-recommended-bump.md) ^12.1.0
- [conventional-changelog-angular](https://npm.io/package/conventional-changelog-angular.md) ^9.4.0
- [@conventional-changelog/git-client](https://npm.io/package/@conventional-changelog/git-client.md) ^3.1.2
- [conventional-changelog-conventionalcommits](https://npm.io/package/conventional-changelog-conventionalcommits.md) ^10.4.0

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 12.0.2 (latest) — 2026-09-14
- 9.0.0-next.0 (next) — 2024-10-08
- 5.0.0-esm.1 (esm) — 2022-04-30
- 1.0.0-beta.0 (beta) — 2019-04-19
- 1.0.0-alpha.1 (alpha) — 2019-04-07
- 12.0.1 — 2026-09-14
- 12.0.0 — 2026-07-25
- 11.0.1 — 2026-05-30
- 11.0.0 — 2026-04-24
- 10.0.6 — 2026-03-13
- 10.0.5 — 2026-02-05
- 10.0.4 — 2025-12-16
- 10.0.3 — 2025-12-11
- 10.0.2 — 2025-11-16
- 10.0.1 — 2025-04-18
- … 41 more at https://npm.io/package/@release-it/conventional-changelog/versions

## README

# Conventional Changelog plugin for release-it

This plugin will provide the recommended bump to release-it, and update the changelog file (e.g. `CHANGELOG.md`).

```
npm install --save-dev @release-it/conventional-changelog
```

## Configuration

In the [release-it][1] config, for example:

```json
"plugins": {
  "@release-it/conventional-changelog": {
    "preset": {
      "name": "angular"
    },
    "infile": "CHANGELOG.md"
  }
}
```

The plugin is a wrapper around conventional-changelog packages [conventional-recommended-bump][2],
[conventional-changelog][3] and more.

## Contents

- [`preset`][4]
- Bump
  - [`commitsOpts`][5]
  - [`tagOpts`][6]
  - [`whatBump`][7]
  - [`ignoreRecommendedBump`][8]
  - [`strictSemVer`][9]
- Changelog
  - [`infile`][10]
  - [`header`][11]
  - [`context`][12]
  - [`gitRawCommitsOpts`][13]
  - [`parserOpts`][14]
  - [`writerOpts`][15]

### `preset`

For `preset.name`, use one of:

- `angular`
- `atom`
- `codemirror`
- `conventionalcommits`
- `ember`
- `eslint`
- `express`
- `jquery`
- `jscs`
- `jshint`

Use an object with `name` and `types` to use a custom preset:

```json
"plugins": {
  "@release-it/conventional-changelog": {
    "infile": "CHANGELOG.md",
    "preset": {
      "name": "conventionalcommits",
      "types": [
        {
          "type": "feat",
          "section": "Features"
        },
        {
          "type": "fix",
          "section": "Bug Fixes"
        },
        {
          "type": "docs",
          "section": "Documentation",
          "effect": "changelog"
        },
        {
          "type": "chore",
          "effect": "hidden"
        }
      ]
    }
  }
}
```

This is passed as the first argument to [`bumper.loadPreset`][16] (in both bumper and changelog writer).

With the `conventionalcommits` preset, `types[].effect` controls changelog visibility and recommended bumps for
non-breaking commits:

- `bump` includes the commit in the changelog and bump recommendation. This is the default.
- `changelog` includes the commit in the changelog without triggering a bump.
- `hidden` excludes the commit from both.

Breaking changes still trigger a major bump regardless of their type effect. See the
[Conventional Commits preset options][17] for the full configuration contract.

## Bump

### `tagOpts`

- This option will be passed as the first argument to [`bumper.tag`][16]
- [Type definition for `tagOpts` → look for `GetSemverTagsParams`][18]

### `commitsOpts`

- This option will be passed as the first argument to [`bumper.commits`][16]
- [Type definition for `commitsOpts` → look for `GetCommitsParams`][18]

### `whatBump`

- This option will be passed as the first argument to [`bumper.bump`][16]
- [Type definition for `whatBump` → look for `Preset['whatBump']`][19]
- Use `false` to skip releasing a new version:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "whatBump": false
    }
  }
}
```

- Use a function to manually provide a bump:

```js
module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      whatBump: function () {
        return { releaseType: '10.0.1' };
      }
    }
  }
};
```

### `ignoreRecommendedBump`

Default value: `false`

Use `true` to ignore the recommended bump, and use the version provided by release-it (command line argument or prompt).

Note that the changelog preview shows the recommended bump, as the desired version isn't known yet in the release-it
process. The `infile` will have the correct version.

### `strictSemVer`

Default value: `false`

Use `true` to strictly follow semver, also in consecutive pre-releases. This means that from a pre-release, a
recommended bump will result in a next pre-release for the next version.

For example, from `1.0.0-alpha.0` a recommended bump of `minor` will result in a `preminor` bump to `1.1.0-alpha.0`.

The default behavior results in a `prerelease` bump to `1.0.0-alpha.1`.

### Promoting a pre-release

The release-it `git.tagExclude` option only affects release-it's version lookup. The recommended bump and changelog
writer have their own tag policies. Configure all three when a stable release should include every commit since the
previous stable version:

```json
{
  "git": {
    "tagExclude": "*.*.*-*"
  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "tagOpts": {
        "skipUnstable": true
      },
      "writerOpts": {
        "generateOn": null
      }
    }
  }
}
```

`tagOpts.skipUnstable` calculates the recommendation from the previous stable tag. `writerOpts.generateOn: null` keeps
intermediate prerelease tags from splitting those commits into separate changelog blocks.

## Changelog

### `infile`

Default value: `undefined`

- Set a filename as `infile` to write the changelog to. If this file does not exist yet, it's created with the full
  history.
- When `infile` is not set, the changelog generated by this plugin will still be used as release notes for e.g. [GitHub
  Releases][20].
- Set `infile: false` to disable the changelog writing (and only use the recommended bump for the next version).

### `header`

Default value: `"# Changelog"`

Set the main header for the changelog document:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "infile": "CHANGELOG.md",
      "header": "# Changelog",
      "preset": {
        "name": "conventionalcommits"
      }
    }
  }
}
```

### `context`

Default value: `undefined`

This option will be passed as the second argument (`context`) to [conventional-changelog][21], for example:

```json
"plugins": {
  "@release-it/conventional-changelog": {
    "context": {
      "linkCompare": false
    }
  }
}
```

### `gitRawCommitsOpts`

Default value: `undefined`

Options for [`git-raw-commits`][22]. For example, you can use the following option to include merge commits into
changelog:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "gitRawCommitsOpts": {
        "merges": null
      }
    }
  }
}
```

### `parserOpts`

- Default value: `undefined`
- Options for [`conventional-commits-parser`][23]
- This option will also be passed as the second argument to [`bumper.parserOptions`][16]
- [Type definition for `parserOpts` → look for `ParserOptions`][24]

For example, you can use the following option to set the merge pattern during parsing the commit message:

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "parserOpts": {
        "mergePattern": "^Merge pull request #(\\d+) from (.*)$"
      }
    }
  }
}
```

### `writerOpts`

- Default value: `undefined`
- Options for [`conventional-changelog-writer`][25]
- [Type definition for `writerOpts` → look for `Options`][26]

For example, you can use the following option to group the commits by 'scope' instead of 'type' by default.

```json
{
  "plugins": {
    "@release-it/conventional-changelog": {
      "writerOpts": {
        "groupBy": "scope"
      }
    }
  }
}
```

Customize the render functions in a `.release-it.js` file:

```js
module.exports = {
  plugins: {
    '@release-it/conventional-changelog': {
      writerOpts: {
        commitPartial: (_context, commit) => `- ${commit.header}`
      }
    }
  }
};
```

`template`, `headerPartial`, `preamblePartial`, `commitPartial`, and `footerPartial` accept render functions.
Handlebars template strings and partial files are no longer supported.

A custom `writerOpts.transform` **replaces** the preset's own transform (the one that maps commit types to
sections via [`preset.types`](#preset) and strips types with `effect: "hidden"`). Override it and you lose that
behavior. Raw types and hidden entries reappear. To filter or reshape the output while keeping the preset behavior, use
[`finalizeContext`][26] instead.

Since `conventional-changelog-writer@9`, the `commit` passed to `transform` is **read-only**. Return an
extended object instead of mutating it:

```js
// Wrong: no-op or throws, the commit is read-only
transform: commit => { commit.scope = '...'; return commit; }

// Right: return an extended copy
transform: commit => ({ ...commit, scope: '...' })
```

## Command-line

Options for this plugin can be set from the command line. Some examples:

```
release-it --plugins.@release-it/conventional-changelog.infile=history.md
release-it --no-plugins.@release-it/conventional-changelog.infile
```

- Keys are separated by dots.
- Values can be negated by prefixing the key with `no-`.
- Arguments may need to be single-quoted (`'`) such as `--'deep.key=value'` or `'--deep.key=value'`

Depending on your shell or OS this may differ.

## GitHub Actions

When using this plugin in a GitHub Action, make sure to set [`fetch-depth: 0`][27] so the history is available to
determine the correct recommended bump and changelog.

Also see [https://github.com/release-it/release-it/blob/main/docs/ci.md#github-actions][28]

## Troubleshooting

### `parseCommits is not a function`

`@conventional-changelog/git-client` dynamically imports [`conventional-commits-parser`][23] and needs
**v7**. This error means your dependency tree resolved an older incompatible version. Usually another dependency
(e.g. `@commitlint/cli`) pulls in an older version, and `legacy-peer-deps=true` (or the yarn/pnpm equivalent) lets it
win over git-client's `^7` peer requirement.

Check which version is resolved:

```
npm ls conventional-commits-parser
```

Then fix it on your side with one of:

- Force a single v7 via `overrides` (npm) / `resolutions` (yarn) / `pnpm.overrides`:
  ```json
  {
    "overrides": {
      "conventional-commits-parser": "^7"
    }
  }
  ```
- Remove `legacy-peer-deps=true` from your `.npmrc` so the `^7` peer requirement is honored.
- Update the conflicting dependency (e.g. `@commitlint/*`) to a version that uses v7.

[1]: https://github.com/release-it/release-it
[2]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-recommended-bump#readme
[3]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog#readme
[4]: #preset
[5]: #commitsopts
[6]: #tagopts
[7]: #whatbump
[8]: #ignorerecommendedbump
[9]: #strictsemver
[10]: #infile
[11]: #header
[12]: #context
[13]: #gitrawcommitsopts
[14]: #parseropts
[15]: #writeropts
[16]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/README.md#api
[17]: https://conventional-changelog.js.org/presets/conventional-commits/
[18]: https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/git-client/src/types.ts
[19]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-recommended-bump/src/types.ts
[20]: https://github.com/release-it/release-it/blob/main/docs/github-releases.md
[21]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog#readme
[22]: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits#api
[23]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-commits-parser#api
[24]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-commits-parser/src/types.ts
[25]:
  https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer#api
[26]:
  https://github.com/conventional-changelog/conventional-changelog/blob/master/packages/conventional-changelog-writer/src/types/options.ts
[27]: https://github.com/actions/checkout#fetch-all-history-for-all-tags-and-branches
[28]: https://github.com/release-it/release-it/blob/main/docs/ci.md#github-actions

---
_Source: https://npm.io/package/@release-it/conventional-changelog · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._