npm package: @hypernym/changelog
Description: Git Changelog Generator.
Author: Hypernym Studio
Latest version: 0.3.0

<h1 align="center">@hypernym/changelog</h1>

<p align="center">Git Changelog Generator.</p>

<br>

<pre align="center">pnpm add -D @hypernym/changelog</pre>

<br>

## 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.

```sh
npx hyperchangelog
```

### Existing Repository

> [!NOTE]
>
> Generates release notes based on all existing tags and commits.

```sh
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](#enhance) can be easily enabled via config.

Here is an example of a changelog file:

```md
# 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](https://www.npmjs.com/package/@hypernym/changelog):

- [@hypernym/bundler](https://github.com/hypernym-studio/bundler)
- [@hypernym/frame](https://github.com/hypernym-studio/frame)
- [@hypernym/emitter](https://github.com/hypernym-studio/emitter)
- [@hypernym/merge](https://github.com/hypernym-studio/merge)
- [@hypernym/args](https://github.com/hypernym-studio/args)
- [@hypernym/utils](https://github.com/hypernym-studio/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.

```json
{
  "$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.

```sh
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`.

```json
{
  "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: `'#'`.

```json
{
  "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: `'#'`.

```json
{
  "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:

```json
{
  "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:

```json
{
  "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: `[]`.

```json
{
  "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: `''`.

```json
{
  "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`.

```json
{
  "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.

```json
{
  "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.

```sh
npx hyperchangelog --sync
```

### --clean

- Type: `boolean`
- Default: `false`

Specifies whether the generator forces a full fresh rewrite.

```sh
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:

```sh
npx hyperchangelog --copy
```

It is possible to specify a custom path:

```sh
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.

```sh
npx hyperchangelog --config changelog.json
```

### --cwd

- Type: `string`
- Default: `cwd`

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

```sh
npx hyperchangelog --cwd ./custom-dir
```

## License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the [MIT](LICENSE.txt) license.