# conventional-changelog-core

> Core package of conventional-changelog.

Latest version **9.0.0** (published 2025-02-16) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install conventional-changelog-core
pnpm add conventional-changelog-core
yarn add conventional-changelog-core
bun add conventional-changelog-core
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 9.0.0 |
| Published | 2025-02-16 |
| First published | 2015-12-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/conventional-changelog-core) |
| Module format | ESM |
| Node | >=18 |
| Dependencies | 9 |
| Unpacked size | 25.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8506 |
| Author | Steve Mao |
| Maintainers | bcoe, oss-bot, dangreen, stevemao, tapppi |
| Keywords | conventional-changelog, conventional, changelog, log |

## Links

- npm: https://www.npmjs.com/package/conventional-changelog-core
- Repository: https://github.com/conventional-changelog/conventional-changelog
- Homepage: https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-core#readme
- Issues: https://github.com/conventional-changelog/conventional-changelog/issues
- npm.io page: https://npm.io/package/conventional-changelog-core

## Dependencies (9)

- [add-stream](https://npm.io/package/add-stream.md) ^1.0.0
- [fd-package-json](https://npm.io/package/fd-package-json.md) ^1.2.0
- [git-raw-commits](https://npm.io/package/git-raw-commits.md) ^5.0.0
- [git-semver-tags](https://npm.io/package/git-semver-tags.md) ^8.0.0
- [hosted-git-info](https://npm.io/package/hosted-git-info.md) ^8.0.0
- [normalize-package-data](https://npm.io/package/normalize-package-data.md) ^7.0.0
- [conventional-commits-parser](https://npm.io/package/conventional-commits-parser.md) ^6.1.0
- [@hutson/parse-repository-url](https://npm.io/package/@hutson/parse-repository-url.md) ^5.0.0
- [conventional-changelog-writer](https://npm.io/package/conventional-changelog-writer.md) ^8.0.1

## 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

- 9.0.0 (latest) — 2025-02-16
- 4.2.1 (next) — 2020-11-05
- 8.0.0 — 2024-05-03
- 7.0.0 — 2023-09-08
- 6.0.0 — 2023-08-27
- 5.0.2 — 2023-06-28
- 5.0.1 — 2023-06-06
- 5.0.0 — 2023-06-06
- 4.2.4 — 2021-09-09
- 4.2.3 — 2021-07-03
- 4.2.2 — 2020-12-30
- 4.2.0 — 2020-08-12
- 4.1.8 — 2020-06-20
- 4.1.7 — 2020-05-08
- 4.1.6 — 2020-05-08
- … 54 more at https://npm.io/package/conventional-changelog-core/versions

## README

#  [![NPM version][npm-image]][npm-url] [![Build Status: Linux][travis-image]][travis-url] [![Build Status: Windows][appveyor-image]][appveyor-url] [![Dependency Status][daviddm-image]][daviddm-url] [![Coverage Status][coverage-image]][coverage-url]

> [conventional-changelog](https://github.com/conventional-changelog/conventional-changelog) core

You are probably looking for the [cli](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-cli) module. Or use one of the plugins if you are already using the tool:  [grunt](https://github.com/btford/grunt-conventional-changelog)/[gulp](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/gulp-conventional-changelog)/[atom](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-atom).

## Usage

```sh
$ npm install --save conventional-changelog-core
```

```js
import conventionalChangelogCore from 'conventional-changelog-core';

conventionalChangelogCore()
  .pipe(process.stdout); // or any writable stream
```

## API

### conventionalChangelogCore([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])

Returns a readable stream.

*Note:* [`options.transform`](#transform-1), [`options.pkg.transform`](#transform) and [`writerOpts.transform`](https://github.com/conventional-changelog/conventional-changelog-writer#transform) are different. If you have a better naming suggestion, please send a PR.

#### options

##### config

Type: `promise`, `function` or `object`

This should serve as default values for other arguments of `conventionalChangelogCore` so you don't need to rewrite the same or similar config across your projects. Any value in this could be overwritten.
If this is a promise (recommended if async), it should resolve with the config.
If this is a function, it expects a node style callback with the config object.
If this is an object, it is the config object. The config object should include `context`, `gitRawCommitsOpts`, `parserOpts` and `writerOpts`.

##### pkg

Type: `object`

###### path

Type: `string` Default: [closest package.json](https://github.com/sindresorhus/read-package-up).

The location of your "package.json".

###### transform

Type: `function` Default: pass through.

A function that takes `package.json` data as the argument and returns the modified data. Note this is performed before normalizing package.json data. Useful when you need to add a leading 'v' to your version or modify your repository url, etc.

##### append

Type: `boolean` Default: `false`

Should the log be appended to existing data.

##### releaseCount

Type: `number` Default: `1`

How many releases of changelog you want to generate. It counts from the upcoming release. Useful when you forgot to generate any previous changelog. Set to `0` to regenerate all.

##### skipUnstable

Type: `boolean` Default: `false`

If set, unstable release tags will be skipped, e.g., x.x.x-rc.

##### debug

Type: `function` Default: `function() {}`

A debug function. EG: `console.debug.bind(console)`

##### warn

Type: `function` Default: `options.debug`

A warn function. EG: `grunt.verbose.writeln`

##### transform

Type: `function` Default: get the version (without leading 'v') from tag and format date.

###### function(commit, cb)

A transform function that applies after the parser and before the writer.

This is the place to modify the parsed commits.

####### commit

The commit from conventional-commits-parser.

####### cb

Callback when you are done.

####### this

`this` arg of transform handler of a stream.

##### outputUnreleased

Type: `boolean` Default: `true` if a different version than last release is given. Otherwise `false`.

If this value is `true` and `context.version` equals last release then `context.version` will be changed to `'Unreleased'`.

**NOTE:** You may want to combine this option with `releaseCount` set to `0` to always overwrite the whole CHANGELOG. `conventional-changelog` only outputs a CHANGELOG but doesn't read any existing one.

##### lernaPackage

Specify a package in lerna-style monorepo that the CHANGELOG should be generated for.

Lerna tags releases in the format `foo-package@1.0.0` and assumes that packages
are stored in the directory structure `./packages/foo-package`.

##### tagPrefix

Specify a prefix for the git tag that will be taken into account during the comparison.
For instance if your version tag is prefixed by `version/` instead of `v` you would specify `--tagPrefix=version/`

#### context

See the [conventional-changelog-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer) docs. There are some defaults or changes:

##### host

Default: normalized host found in `package.json`.

##### version

Default: version found in `package.json`.

##### owner

Default: extracted from normalized `package.json` `repository.url` field.

##### repository

Default: extracted from normalized `package.json` `repository.url` field.

##### repoUrl

Default: The whole normalized repository url in `package.json`.

##### gitSemverTags

Type: `array`

All git semver tags found in the repository. You can't overwrite this value.

##### previousTag

Type: `string` Default: previous semver tag or the first commit hash if no previous tag.

##### currentTag

Type: `string` Default: current semver tag or `'v'` + version if no current tag.

##### packageData

Type: `object`

Your `package.json` data. You can't overwrite this value.

##### linkCompare

Type: `boolean` Default: `true` if `previousTag` and `currentTag` are truthy.

Should link to the page that compares current tag with previous tag?

#### gitRawCommitsOpts

See the [git-raw-commits](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/git-raw-commits) docs. There are some defaults:

##### format

Default: `'%B%n-hash-%n%H%n-gitTags-%n%d%n-committerDate-%n%ci'`

##### from

Default: based on `options.releaseCount`.

##### reverse

Default: `true` if `options.append` is truthy.

##### debug

Type: `function` Default: `options.debug`

#### parserOpts

See the [conventional-commits-parser](https://github.com/conventional-changelog/conventional-commits-parser) docs.

##### warn

Default: `options.warn`

#### writerOpts

See the [conventional-changelog-writer](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-writer) docs. There are some defaults:

##### finalizeContext

Finalize context is used for generating above context.

**NOTE:** If you overwrite this value the above context defaults will be gone.

##### debug

Type: `function` Default: `options.debug`

##### reverse

Default: `options.append`

##### doFlush

Default: `options.outputUnreleased`


## Notes for parent modules

This module has options `append` and `releaseCount`. However, it doesn't read your previous changelog. Reasons being:

1. The old logs is just to be appended or prepended to the newly generated logs, which is a very simple thing that could be done in the parent module.
2. We want it to be very flexible for the parent module. You could create a readable stream from the file or you could just read the file.
3. We want the duty of this module to be very minimum.

So, when you build a parent module, you need to read the old logs and append or prepend to them based on `options.append`. However, if `options.releaseCount` is `0` you need to ignore any previous logs. Please see [conventional-github-releaser](https://github.com/conventional-changelog/conventional-github-releaser) as an example.

Arguments passed to `conventionalChangelogCore` will be mutated.


## License

MIT


[npm-image]: https://badge.fury.io/js/conventional-changelog-core.svg
[npm-url]: https://npmjs.org/package/conventional-changelog-core
[travis-image]: https://travis-ci.org/conventional-changelog/conventional-changelog-core.svg?branch=master
[travis-url]: https://travis-ci.org/conventional-changelog/conventional-changelog-core
[appveyor-image]: https://ci.appveyor.com/api/projects/status/baoumm34w8c5o0hv/branch/master?svg=true
[appveyor-url]: https://ci.appveyor.com/project/stevemao/conventional-changelog-core/branch/master
[daviddm-image]: https://david-dm.org/conventional-changelog/conventional-changelog-core.svg?theme=shields.io
[daviddm-url]: https://david-dm.org/conventional-changelog/conventional-changelog-core
[coverage-image]: https://coveralls.io/repos/github/conventional-changelog/conventional-changelog/badge.svg?branch=master
[coverage-url]: https://coveralls.io/github/conventional-changelog/conventional-changelog?branch=master

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