Introduction

This is a simple generator that creates a changelog file using git metadata.

To automatically generate release notes, it is necessary to commit some changes to the repository or already have existing commits and tags.

Quick Start

[!IMPORTANT]

Make a backup of the current CHANGELOG.md file before use as it may be overwritten or changed.

New Repository

[!NOTE]

Generates release notes based on the latest package.json version and existing commits.

npx hyperchangelog

Existing Repository

[!NOTE]

Generates release notes based on all existing tags and commits.

npx hyperchangelog --sync

CHANGELOG.md

By default, it will create a file in the project root in private mode, which means it won't add actual hashes and PR links since this can be useful for repos whose codebases are not public.

These additional enhancements can be easily enabled via config.

Here is an example of a changelog file:

# What's New

Check out the latest features and improvements from @hypernym/changelog package.

This file is automatically generated by @hypernym/changelog.

## v0.1.0

Version generated on March 30, 2026

### Features

- feat: add new skip option ([#6](#)) by [ivodolenc](https://github.com/ivodolenc)
- feat: add new copy option ([#5](#)) by [ivodolenc](https://github.com/ivodolenc)
- feat: add new contributors option ([#4](#)) by [ivodolenc](https://github.com/ivodolenc)
- feat: add new clean option ([#3](#)) by [ivodolenc](https://github.com/ivodolenc)
- feat: add config schema ([#2](#)) by [ivodolenc](https://github.com/ivodolenc)
- feat: add changelog generator ([#1](#)) by [ivodolenc](https://github.com/ivodolenc)

### Bug Fixes

- fix: improve PR details in commit messages

### Refactors

- refactor: improve schema config
- refactor: improve config file options
- refactor: improve commit groups
- refactor: add bin main entry
- refactor: add pkg meta
- refactor: add utils

### Types

- types: update Args types
- types: add types

### Documentation

- docs: improve options info
- docs: add clean option info
- docs: improve info
- docs: add new config info
- docs: add readme

### Other

- chore: update pkg homepage
- chore: add schema to changelog config
- chore: add schema entry to bundler config
- chore: add changelog config
- chore: enable minification
- chore: update dependencies
- chore: add pkg files
- chore: add bundler main config
- chore: add tsconfig
- chore: add oxc configs
- chore: add vscode configs
- chore: add .editorconfig file
- chore: add license
- Initial commit

### Authors

- Ivo Dolenc ([ivodolenc](https://github.com/ivodolenc))

Showcase

Here are some projects that use @hypernym/changelog:

• @hypernym/bundler
• @hypernym/frame
• @hypernym/emitter
• @hypernym/merge
• @hypernym/args
• @hypernym/utils

Config

[!NOTE]

Configuration file and all options are optional.

Hyperchangelog automatically looks for the changelog.config.json file in the project root.

changelog.config.json

The configuration file allows defining and customizing the changelog behavior.

{
  "$schema": "./node_modules/@hypernym/changelog/dist/schema.json",
  "enhance": {
    "hash": true,
    "PR": true,
    "contributors": true
  },
  "authors": {
    "Ivo Dolenc": {
      "user": "ivodolenc",
      "link": "https://github.com/ivodolenc"
    }
  },
  "repoUrl": "https://github.com/user/repo"
}

Custom path

Additionally, it is possible to specify a custom path to the configuration file.

npx hyperchangelog --config changelog.json

Options

enhance

• Type: object
• Default: undefined

Enables various additional enhancements to the changelog.

• hash - Enables hash link for each commit. Default: false.
• PR - Enables pull request details in commits. Default: false.
• contributors - Enables contributors list for each version. Default: false.

{
  "enhance": {
    "hash": true,
    "PR": true,
    "contributors": true
  }
}

contributors

• Type: object
• Default: undefined

Specifies a list of custom contributors.

It is also used to map the commit author's name to a user and profile link on GitHub.

• user - Specifies a custom GitHub username.
• link - Specifies a custom link that opens when the username is clicked. Default: '#'.

{
  "contributors": {
    "Ivo Dolenc": {
      "user": "ivodolenc",
      "link": "https://github.com/ivodolenc"
    },
    "Hypernym Studio": {
      "user": "hypernym",
      "link": "https://github.com/hypernym-studio"
    }
  }
}

authors

• Type: object
• Default: undefined

Specifies a list of custom authors.

• user - Specifies a custom GitHub username.
• link - Specifies a custom link that opens when the username is clicked. Default: '#'.

{
  "authors": {
    "Ivo Dolenc": {
      "user": "ivodolenc",
      "link": "https://github.com/ivodolenc"
    },
    "Hypernym Studio": {
      "user": "hypernym",
      "link": "https://github.com/hypernym-studio"
    }
  }
}

metadata

[!NOTE]

Experimental.

• Type: object
• Default: undefined

Specifies custom metadata.

• position - Type: number | 'start' | 'end'. Default: 'start'.
• commits - Type: { message: string }[]. Required: true.
• date - Type: string. Default: undefined.

Allows adding completely new versions with specific metadata:

{
  "metadata": {
    "v0.0.0": {
      "position": "start",
      "commits": [
        {
          "message": "docs: custom commit message"
        },
        {
          "message": "chore: custom commit message"
        }
      ],
      "date": "2026-04-02"
    }
  }
}

It is also possible to customize existing tag versions:

{
  "metadata": {
    "v0.1.0": {
      "commits": [
        {
          "message": "custom message"
        }
      ],
      "date": "2026-04-02"
    }
  }
}

commits

• Type: object
• Default: undefined

Specifies custom commits options.

• skip - Specifies custom skip options. Default: undefined.
• • messages - Specifies a list of custom string or regex patterns used to skip commits by message. Default: [].
• • tags - Specifies a list of custom string or regex patterns used to skip commits by tags. Default: [].

{
  "commits": {
    "skip": {
      "messages": [],
      "tags": []
    }
  }
}

tags

• Type: object
• Default: undefined

Specifies custom tags options.

• prefix - Specifies the version tag prefix. Example: [prefix]0.1.0. Default: v.
• suffix - Specifies the version tag suffix. Example: 0.1.0[suffix]. Default: ''.

{
  "tags": {
    "prefix": "v",
    "suffix": "-special-version"
  }
}

file

• Type: object
• Default: undefined

Specifies custom changelog file options.

• path - Default: [cwd]/CHANGELOG.md.
• heading - Default: What's New.
• description - Default: Check out the latest features and improvements.
• pkgName - Default: true.

{
  "file": {
    "path": "CHANGELOG.md",
    "heading": "What's New",
    "description": "Check out the latest features and improvements",
    "pkgName": true
  }
}

repoUrl

• Type: string
• Default: ''

Specifies a custom repository URL. Required when enabling enhanced links.

By default, it scans package.json file for repository.url property.

{
  "repoUrl": "https://github.com/user/repo"
}

CLI

--sync

• Type: boolean
• Default: false

Specifies whether the generator will sync the current metadata and write a changelog accordingly.

Intended for cases where it is necessary to generate release notes based on existing tags and commits.

npx hyperchangelog --sync

--clean

• Type: boolean
• Default: false

Specifies whether the generator forces a full fresh rewrite.

npx hyperchangelog --clean

--copy

• Type: boolean | string
• Default: false

Specifies whether the changelog file is copied to a custom location after completion.

By default, if no custom path is specified, the changelog is copied to the ./dist directory:

npx hyperchangelog --copy

It is possible to specify a custom path:

npx hyperchangelog --copy ./custom/dir

--config

• Type: string
• Default: changelog.config.json

Specifies the path to the configuration file. Only the .json format is supported at the moment.

npx hyperchangelog --config changelog.json

--cwd

• Type: string
• Default: cwd

Specifies the path to the project root (current working directory).

npx hyperchangelog --cwd ./custom-dir

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.