conventional-changelog

conventional-changelog is the core generator in the conventional-changelog monorepo: it reads a project’s git history, filters and parses commits against a conventional-commits convention (Angular, Conventional Commits, or a custom preset), and writes a formatted changelog to stdout or a CHANGELOG.md file. It ships both a CLI (conventional-changelog -p angular) and a fluent, promise-based JS API (new ConventionalChangelog().readPackage().loadPreset('angular').write()) built on async generators, so it streams output rather than buffering an entire changelog in memory.

Internally it composes several independently versioned sibling packages from the same monorepo — a git client for walking tags and commits, a commit parser, a commit filter, a changelog writer/templater, and a preset loader — giving downstream tools (semantic-release-style automation, standard-changelog, custom release scripts) a stable, swappable set of building blocks rather than one monolithic library.

What You Get

• A CLI (conventional-changelog) that generates or appends a CHANGELOG.md from git history in one command
• A fluent ConventionalChangelog builder class with a promise-based API for reading package.json, loading a preset, and streaming changelog output
• Built-in support for pluggable presets (Angular is the reference preset) via a dedicated preset-loader package
• Host-aware link generation for GitHub, GitLab, and Bitbucket issue/commit/compare URLs
• Streaming output via Node.js Readable streams and async generators instead of buffering the full changelog in memory
• Automatic detection of unreleased versions and semver tag ranges so re-running the tool only adds new entries

Common Use Cases

• Wiring changelog generation into an npm release or version script so CHANGELOG.md updates automatically from commit messages
• Building custom release automation on top of the JS API instead of shelling out to the CLI
• Generating changelogs for monorepo packages that need per-package tag ranges and repository links
• Producing GitHub/GitLab-linked release notes (issue references, commit links, compare URLs) without hand-writing markdown

Under The Hood

Architecture The package centers on the ConventionalChangelog class, a fluent builder whose methods (readPackage, loadPreset, config, tags, commits, writer, options) each merge partial parameters into an internal params promise via composeParams, deferring all resolution until write() is called. write() then orchestrates the whole pipeline: it fetches semver tags and raw commits from a ConventionalGitClient (from the sibling @conventional-changelog/git-client package), transforms each commit through transformCommit, and pipes the result into writeChangelog from conventional-changelog-writer, all exposed as an async generator so writeStream() can wrap it in a Node Readable. Host-specific link behavior (GitHub/GitLab/Bitbucket) lives in small dedicated modules under src/hosts/, keeping per-host formatting isolated from the core write path. This is a genuinely modular design: presets, parsing, filtering, writing, and git access are each separately versioned workspace packages rather than internal files, so consumers can swap or reuse individual pieces.

Tech Stack ESM-only TypeScript targeting Node >=22, built and versioned inside a pnpm workspace monorepo alongside its sibling packages (@conventional-changelog/git-client, conventional-changelog-writer, conventional-changelog-preset-loader, conventional-commits-parser, conventional-commits-filter, conventional-changelog-angular). The CLI is built on the project’s own lightweight argue-cli parser (a recent replacement for meow), package.json handling goes through fd-package-json and @simple-libs/normalize-package-data, and repository URLs are parsed with @simple-libs/hosted-git-info. Linting runs through oxlint (a Rust-based linter) rather than ESLint, tests run on Vitest, and the monorepo’s docs site is a separate Astro app built and deployed via its own CI workflow.

Code Quality The package has a focused Vitest test suite (ConventionalChangelog.spec.ts, cli/index.spec.ts) built around a custom TestTools harness and the better-than-before library, which sets up staged, incrementally-mutated real git repositories as fixtures rather than mocking git calls — a heavier but more realistic testing approach than pure unit mocks. TypeScript is used throughout with explicit exported types (Options, Params, Preset, HostOptions) and a test:types script that runs tsc --noEmit as its own CI check. Error handling favors explicit try/catch with deliberate fallback (e.g. silently falling back to git config for a repository URL when package.json lacks one) over silent swallowing. CI (tests.yaml, checks.yml) enforces lint, type-check, and unit tests on every push, and commit messages themselves are enforced via commitlint and a pre-commit hook.

What Makes It Unique Rather than being a single all-in-one changelog generator, this package is the orchestration layer over a deliberately decomposed set of sibling packages (git client, parser, filter, writer, preset loader) that are each independently publishable — letting other tools in the ecosystem (or third-party release automation) depend on just the piece they need instead of the whole CLI. The fluent, chainable builder API composing async generators for streaming output, combined with automatic unreleased-version and semver-range detection, is a thoughtful evolution of the original conventional-changelog design rather than a fundamentally novel approach to changelog generation.