or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdgit-integration.mdindex.mdprogrammatic-api.md
tile.json

tessl/npm-conventional-changelog

Generate a changelog from git metadata using conventional commit conventions.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/conventional-changelog@7.1.x

To install, run

npx @tessl/cli install tessl/npm-conventional-changelog@7.1.0

index.mddocs/

Conventional Changelog

Conventional Changelog is a command-line tool and JavaScript library for generating changelogs from git metadata using conventional commit conventions. It parses commit messages following established patterns (like Angular commit convention), extracts meaningful information about features, fixes, and breaking changes, and formats them into structured changelog documents. The tool supports multiple preset configurations, offers both programmatic API access and CLI usage, and integrates seamlessly with monorepo structures and CI/CD workflows.

Package Information

  • Package Name: conventional-changelog
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install conventional-changelog

Core Imports

import { 
  ConventionalChangelog,
  parseHostedGitUrl,
  runProgram,
  flags,
  type Options,
  type Preset,
  type HostedGitInfo,
  type Commit
} from "conventional-changelog";

For CommonJS:

const { 
  ConventionalChangelog,
  parseHostedGitUrl,
  runProgram
} = require("conventional-changelog");

Basic Usage

import { ConventionalChangelog } from "conventional-changelog";

// Create a new changelog generator
const changelog = new ConventionalChangelog(process.cwd());

// Configure with preset and generate changelog
changelog
  .loadPreset("angular")
  .readPackage()
  .readRepository();

// Generate changelog as async generator
for await (const chunk of changelog.write()) {
  console.log(chunk);
}

Architecture

Conventional Changelog is built around several key components:

  • ConventionalChangelog Class: Main API providing fluent interface for configuration and generation
  • CLI Interface: Command-line tool with comprehensive options for various workflows
  • Preset System: Pluggable configuration system supporting various commit conventions
  • Git Integration: Deep integration with git for reading commits, tags, and repository metadata
  • Host Support: Platform-specific integrations for GitHub, GitLab, and Bitbucket
  • Transform Pipeline: Configurable transformation system for commits and output formatting

Capabilities

Programmatic API

The core ConventionalChangelog class provides a fluent API for generating changelogs programmatically with extensive configuration options and output formats.

interface ConventionalGitClient {
  cwd: string;
  getSemverTags(params?: GetSemverTagsParams): AsyncGenerator<string>;
  getCommits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): AsyncGenerator<Commit>;
  verify(ref: string): Promise<void>;
  getConfig(key: string): Promise<string>;
}

interface Details<T> {
  context: Context;
  commits: T[];
  keyCommit?: T;
}

interface PresetParams<T = any> {
  name?: string;
  [key: string]: any;
}

interface PresetModuleLoader {
  (name: string): Promise<any>;
}

class ConventionalChangelog {
  constructor(cwdOrGitClient?: string | ConventionalGitClient);
  
  // Configuration methods
  loadPreset<T>(preset: PresetParams<T>, loader?: PresetModuleLoader): this;
  config(config: Preset | Promise<Preset>): this;
  readPackage(transform?: PackageTransform): this;
  readPackage(path?: string, transform?: PackageTransform): this;
  package(pkg: Record<string, unknown>): this;
  readRepository(): this;
  repository(infoOrGitUrl: string | Partial<HostedGitInfo>): this;
  options(options: Options): this;
  context(context: Context): this;
  tags(params: GetSemverTagsParams): this;
  commits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): this;
  writer(params: WriterOptions): this;
  
  // Generation methods
  write(includeDetails?: false): AsyncGenerator<string, void>;
  write(includeDetails: true): AsyncGenerator<Details<Commit>, void>;
  writeStream(includeDetails?: boolean): NodeJS.ReadableStream;
}

Programmatic API

Command Line Interface

Complete CLI with comprehensive options for changelog generation, supporting various workflows from simple one-off generations to complex CI/CD integrations.

interface Flags {
  infile?: string;
  outfile?: string;
  stdout?: boolean;
  preset?: string;
  pkg?: string;
  append?: boolean;
  releaseCount?: number;
  skipUnstable?: boolean;
  outputUnreleased?: boolean;
  verbose?: boolean;
  config?: string;
  context?: string;
  firstRelease?: boolean;
  lernaPackage?: string;
  tagPrefix?: string;
}

function runProgram(generator: ConventionalChangelog, flags: Flags): Promise<void>;

Command Line Interface

Configuration and Options

Comprehensive configuration system supporting presets, custom transforms, and detailed output control.

interface Options {
  reset?: boolean;
  append?: boolean;
  releaseCount?: number;
  outputUnreleased?: boolean;
  transformCommit?: CommitTransformFunction;
  warn?: Logger;
  debug?: Logger;
  formatDate?(date: string | Date): string;
}

interface Preset {
  tags?: GetSemverTagsParams;
  commits?: GetCommitsParams;
  parser?: ParserStreamOptions;
  writer?: WriterOptions;
}

Configuration and Options

Git Repository Integration

Git-aware functionality for reading repository metadata, parsing commits, and handling various repository structures including monorepos.

interface HostedGitInfo {
  url: string;
  type: HostType;
  host: string;
  owner?: string;
  project?: string;
}

type HostType = 'github' | 'gitlab' | 'bitbucket' | 'sourcehut' | '';

function parseHostedGitUrl(input: string): HostedGitInfo | null;

Git Repository Integration

Common Types

type Logger = (source: string, messages: string | string[]) => void;

type PackageTransform = (pkg: Package) => Package;

type CommitTransformFunction = (
  commit: Commit, 
  params: Params
) => Partial<Commit> | null | Promise<Partial<Commit> | null>;

interface Package {
  name?: string;
  version?: string;
  description?: string;
  repository?: {
    type?: string;
    url?: string;
  };
  [key: string]: any;
}

interface Commit {
  hash?: string;
  date?: string;
  message?: string;
  subject?: string;
  body?: string;
  type?: string;
  scope?: string;
  notes?: Array<{ title: string; text: string }>;
  references?: Array<{ issue: string; action: string }>;
  gitTags?: string;
  committerDate?: string;
}

interface GetSemverTagsParams {
  prefix?: string;
  skipUnstable?: boolean;
}

interface GetCommitsParams {
  from?: string;
  to?: string;
  path?: string;
  format?: string;
  merges?: boolean;
  reverse?: boolean;
}

interface ParserStreamOptions {
  noteKeywords?: string[];
  referenceActions?: string[];
  issuePrefixes?: string[];
  warn?: Logger;
}

interface WriterOptions {
  finalizeContext?: (context: any, options: any, commits: any, keyCommit: any, originalCommits: any) => any;
  reverse?: boolean;
  doFlush?: boolean;
  debug?: Logger;
}

interface Context {
  version?: string;
  previousTag?: string;
  currentTag?: string;
  host?: string;
  owner?: string;
  repository?: string;
  repoUrl?: string;
  [key: string]: any;
}

interface Params extends Preset {
  commits: GetCommitsParams;
  options: Options;
  context?: Context;
  repository?: Partial<HostedGitInfo> | null;
  package?: Package;
}