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 format its changelog with this formatter by updating .changeset/config.json:

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

This is what wires the formatter into changesets. On every changeset version it writes each release entry with the configured per-line formatting (line prefix, commit hash, capitalization, type-stripping) and, when categorize: true, the emoji category headings.

2. Add a Release Version Script (optional)

changesets wraps the formatter's output inside its own default ### Major Changes, ### Minor Changes, and ### Patch Changes section headings. If you'd rather flatten those and clean up the latest version's sections, run the CLI as a post-processing step right after changeset version:

{
  "scripts": {
    "release:version": "changeset version && changeset-formatter"
  }
}

Then point your Changesets release setup at that script instead of changeset version alone. If you skip this, the changelog is still fully formatted by step 1 — it just keeps changesets' built-in semver section headings.

Why not version / postversion? npm runs postversion automatically, but pnpm disables pre/post lifecycle scripts by default (enable-pre-post-scripts is false), so that spelling silently skips the formatter for pnpm users. A single explicit script runs identically on npm, pnpm, and yarn.

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": {
    "breaking": {
      "title": "Breaking Changes",
      "emoji": "🚨"
    },
    "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.
• A breaking category (for !-marked entries) is built into the defaults; you can still override its title or emoji.

Writing Your Changeset Summaries

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

type: message

Mark an entry as a breaking change with a ! before the colon. The type is irrelevant — feat!, fix!, chore!, etc. all land in the breaking category:

type!: message

For example:

feat: add user authentication flow
fix: correct button alignment
docs: update API reference
fix!: drop support for Node 18

• 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).
• A ! before the colon marks the entry as a breaking change (feat!, fix!, chore!, ...) and routes it to the breaking category regardless of type.
• 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)