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)