changeset-formatter

A customizable changelog formatter for changesets, designed to categorize and style your release notes with emojis, section headers, and release dates.

Features

Categorizes changesets based on their type (e.g., feat, fix, docs) using Conventional Commit style
Supports custom commit types and category titles via config
Outputs changes in a clean, customizable format
Adds a release date to the changelog version header
Supports emoji decoration for each category
Can run automatically as a post-processing script after @changesets/cli

Installation

Install with your preferred package manager:

npm

npm install -D changeset-formatter

pnpm

pnpm add -D changeset-formatter

yarn

yarn add -D changeset-formatter

Requirements

Since this is a custom formatter for changesets, you need to have the @changesets/cli package installed in your project. You can install it using:

npm install -D @changesets/cli

Setup

1. Update Changesets Config

Tell @changesets/cli to use this formatter by updating .changeset/config.json:

- "changelog": "@changesets/cli/changelog",
+ "changelog": "changeset-formatter",

2. Add Post-Processing Script

@changesets/cli doesn’t support customizing section headers directly. To handle that (e.g., adding category titles or dates), run the changeset-formatter CLI as a post-processing step.

Add the following to your package.json scripts:

{
  "scripts": {
    "version": "changeset version",
    "postversion": "changeset-formatter"
  }
}

3. Add a Formatter Config File

To customize how your changelog entries are formatted, create a .changesetformatterrc.json file in the root of your project.

This file lets you control the appearance and structure of the changelog generated by Changesets. Below is the default configuration, you can override any value to suit your needs:

{
  "useEmojis": true,
  "linePrefix": "-",
  "showCommitHash": true,
  "commitHashPosition": "end",
  "capitalizeMessage": true,
  "categorize": false,
  "removeTypes": true,
  "addReleaseDate": true,
  "categories": {
    "feat": {
      "title": "Features",
      "emoji": "✨"
    },
    "fix": {
      "title": "Fixes",
      "emoji": "🛠️"
    },
    "chore": {
      "title": "Chores",
      "emoji": "🏡"
    },
    "docs": {
      "title": "Documentation",
      "emoji": "📖"
    },
    "test": {
      "title": "Tests",
      "emoji": "🧪"
    },
    "ci": {
      "title": "CI",
      "emoji": "🤖"
    },
    "uncategorized": {
      "title": "Uncategorized",
      "emoji": "❓"
    }
  },
  "pathToChangelog": "CHANGELOG.md"
}

Configuration Options

Key	Type	Default	Possible Values / Notes
`useEmojis`	`boolean`	`true`	Whether to display emojis in category headers.
`linePrefix`	`string`	`"-"`	Prefix for each changelog entry (e.g., `"*"`, `"-"`, `""`).
`showCommitHash`	`boolean`	`true`	Append the commit hash to each changelog entry.
`commitHashPosition`	`string`	`"end"`	`"end"` or `"start"` — where to display the commit hash in the line.
`capitalizeMessage`	`boolean`	`true`	Capitalize the first letter of each entry.
`categorize`	`boolean`	`false`	Group changes by category (like Features, Fixes, etc).
`removeTypes`	`boolean`	`true`	Removes the commit type prefix (e.g., `feat:` or `fix:`) from each changelog message. Automatically treated as `true` when `categorize` is enabled.
`addReleaseDate`	`boolean`	`true`	Adds the current date to the version heading (format: `YYYY-MM-DD`).
`categories`	`object`	(see below)	(see below)
`pathToChangelog`	`string`	`"CHANGELOG.md"`	Path to the changelog file. Change if your changelog file is named differently.

Categories Structure

The categories object maps commit types (e.g., feat, fix) to:

A title (category heading)
An optional emoji to display next to the title (if useEmojis is true)

{
  "feat": {
    "title": "Features",
    "emoji": "✨"
  },
  "fix": {
    "title": "Fixes",
    "emoji": "🛠️"
  },
  ...
}

You can add or modify categories to fit your project's needs.
You can define your own types, like "style", "build", "refactor", etc.
A fallback category named uncategorized is used for unknown types if categorization is enabled.

Writing Your Changeset Summaries

To enable categorization each line in a changeset summary should follow the Conventional Commit style:

type: message

For example:

feat: add user authentication flow
fix: correct button alignment
docs: update API reference

Each non-empty line is parsed independently and categorized based on its type.
Type maps to a key in the categories config (e.g., feat, fix, docs).
Unknown or missing types will fall under the uncategorized section (if categorize is enabled).
You can define custom types like style, build or perf in your .changesetformatterrc.json.

Example Output

Here’s how your changelog might look with this formatter:

## 1.2.3 (2025-06-23)

### ✨ Features

- Add new login flow (#abcd123)

### 🛠️ Fixes

- Fix button alignment issue (#bcde234)

### 📖 Documentation

- Update README with config examples (#cdef345)