JS API

The writer takes an iterable of parsed commits plus a context and options, and renders changelog text. Three entry functions cover the common output shapes:

import {
  writeChangelogString,
  writeChangelog,
  writeChangelogStream
} from 'conventional-changelog-writer'

See Introduction for the input shape and a first example.

Rendering functions

writeChangelogString(commits, context?, options?)

Buffers the whole changelog into a string. Simplest option for small histories:

const changelog = await writeChangelogString(commits, context, options)

writeChangelog(context?, options?, includeDetails?)

Returns an async-generator function that takes commits and yields the changelog one release at a time — for use with stream.pipeline:

import { pipeline } from 'node:stream/promises'

await pipeline(
  commitsStream,
  writeChangelog(context, options),
  async function* (releases) {
    for await (const release of releases) {
      process.stdout.write(release)
    }
  }
)

writeChangelogStream(context?, options?, includeDetails?)

Returns a Node.js Transform you can pipe commits through:

commitsStream
  .pipe(writeChangelogStream(context, options))
  .pipe(process.stdout)

includeDetails

Pass includeDetails: true to writeChangelog / writeChangelogStream to emit Details objects instead of Markdown strings.

Context

The context holds release-wide template variables. Common fields:

Field	Type	Description
version	string	Version of the upcoming release (overridden if a commit carries a version).
title	string	Optional release title.
host	string	Host, e.g. https://github.com.
owner	string	Repository owner.
repository	string	Repository name on the host.
repoUrl	string	Full repository URL; used as a fallback when host/owner/repository are absent.
commit	string	URL keyword for commits (default commits).
issue	string	URL keyword for issues (default issues).
linkReferences	boolean	Whether to render links. Auto-enabled when the repository, commit, and issue are known.
date	string	Release date. Defaults to today (UTC), or the key commit’s date.
previousTag, currentTag	string	Tags used to build the comparison URL.
linkCompare	boolean	Link the version to a comparison page. Auto-enabled when both tags are set.

Options

Writer options and their defaults, from the Options type:

Option	Type	Default	Description
transform	(commit, context, options) => Partial<Commit> | null | Promise<…>	defaultCommitTransform	Transform each commit; the returned object is merged into it. Return null to drop it.
groupBy	keyof Commit	'type'	Commit property to group by. Falsy disables grouping.
commitsSort	string | string[] | Comparator	'header'	Sort commits within a group.
commitGroupsSort	string | string[] | Comparator		Sort the commit groups.
notesSort	string | string[] | Comparator	'text'	Sort notes within a group.
noteGroupsSort	string | string[] | Comparator	'title'	Sort the note groups.
generateOn	function | keyof Commit | null	commit has a valid semver version	When to start a new release block.
reverse	boolean	false	Treat upstream commits as chronological instead of reverse-chronological.
ignoreReverted	boolean	true	Drop reverted commits.
doFlush	boolean	true	Flush the remaining commits into a final release block.
skip	(commit) => boolean		Return true to skip a commit.
template	(context) => string | Promise<string>	default	Render a whole release.
headerPartial	function	default	Render the release heading.
preamblePartial	function	default	Render text after the heading.
commitPartial	function	default	Render one commit entry.
footerPartial	function	default	Render the release footer (notes).
finalizeContext	function	pass-through	Last chance to mutate the context before rendering.
formatDate	(date) => string	yyyy-mm-dd (UTC)	Format the release date.
debug	(message) => void	noop	Debug logger.

Templates are functions

The template and *Partial options are render functions that return a string. The defaults come from @conventional-changelog/template, which the writer re-exports so you can compose your own.

Customization

Shape the output by overriding options. This maps commit types to friendly section titles and sorts the groups:

import { writeChangelogString } from 'conventional-changelog-writer'

const sections = {
  feat: 'Features',
  fix: 'Bug Fixes'
}

const changelog = await writeChangelogString(commits, context, {
  transform: commit => ({
    ...commit,
    type: sections[commit.type] ?? commit.type
  }),
  commitGroupsSort: 'title'
})

For deeper control, provide your own template / *Partial render functions, or import the defaults from @conventional-changelog/template and wrap them.

Tip

A preset’s writer object is just a ready-made bundle of these options — pass it as the third argument to skip writing them yourself.

Details objects

Passing includeDetails: true yields structured objects instead of Markdown strings — one per release:

Field	Type	Description
log	string	Rendered Markdown for the release.
keyCommit	Commit | null	The commit that started the release, or null.

for await (const { log, keyCommit } of getStream().pipe(writeChangelogStream(context, options, true))) {
  console.log(keyCommit?.version, log.length)
}

Exports

Export	Description
writeChangelogString	Render commits to a string.
writeChangelog	Async-generator function for pipeline.
writeChangelogStream	Node.js Transform stream.
defaultCommitTransform	The default transform (shortens hash and header, formats the date).
transformCommit	Lower-level helper that applies a transform to a single commit.
formatDate	The default date formatter.

The package also re-exports the building blocks from @conventional-changelog/template — the default template, partial functions, and helpers like heading, link, and list.