or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context-options.mdindex.mdtypes.mdutilities.mdwriters.md
tile.json

index.mddocs/

Conventional Changelog Writer

Conventional Changelog Writer is a TypeScript library that transforms conventional commit data into formatted changelog entries using customizable Handlebars templates. It offers multiple output methods including string generation, async iteration, and stream processing, with extensive configuration options for commit grouping, sorting, and formatting.

Package Information

  • Package Name: conventional-changelog-writer
  • Package Type: npm
  • Language: TypeScript (ESM-only)
  • Installation: npm install conventional-changelog-writer

Core Imports

import {
  writeChangelog,
  writeChangelogStream,
  writeChangelogString,
  transformCommit,
  defaultCommitTransform,
  formatDate,
  stringify,
  createComparator,
  type Context,
  type Options,
  type CommitKnownProps,
  type Details,
  type CommitNote,
  type CommitGroup,
  type NoteGroup,
  type TransformedCommit
} from "conventional-changelog-writer";

For stream integration:

import { Transform } from "stream";

For CommonJS (not recommended as package is ESM-only):

const {
  writeChangelog,
  writeChangelogStream,
  writeChangelogString
} = require("conventional-changelog-writer");

Basic Usage

import {
  writeChangelogString,
  writeChangelog,
  writeChangelogStream,
  type CommitKnownProps,
  type Context,
  type Options
} from "conventional-changelog-writer";

// Sample commits data
const commits: CommitKnownProps[] = [
  {
    hash: "9b1aff905b638aa274a5fc8f88662df446d374bd",
    header: "feat(scope): broadcast $destroy event on scope destruction",
    type: "feat",
    version: "1.0.0",
    committerDate: "2023-01-15",
    notes: [],
    body: null,
    footer: "Closes #1"
  }
];

// Generate changelog as string
const changelog = await writeChangelogString(commits, context, options);
console.log(changelog);

// Generate changelog as async iterable
const generator = writeChangelog(context, options);
for await (const chunk of generator(commits)) {
  console.log(chunk);
}

// Generate changelog as stream
import { pipeline } from "stream/promises";
await pipeline(
  commits,
  writeChangelogStream(context, options),
  process.stdout
);

Architecture

Conventional Changelog Writer is built around several key components:

  • Writer Functions: Three main output formats (string, async generator, stream) for different use cases
  • Commit Transformation: Configurable commit processing pipeline with immutable safety
  • Template System: Handlebars-based rendering with customizable templates and partials
  • Context Management: Rich metadata and repository information for link generation
  • Type Safety: Full TypeScript support with generic commit type constraints
  • CLI Tool: Command-line interface for processing commit files

Capabilities

Changelog Writers

Core changelog generation functions providing multiple output formats for different integration scenarios.

function writeChangelog<Commit extends CommitKnownProps = CommitKnownProps>(
  context?: Context<Commit>,
  options?: Options<Commit>,
  includeDetails?: false
): (commits: Iterable<Commit> | AsyncIterable<Commit>) => AsyncGenerator<string, void>;

function writeChangelogString<Commit extends CommitKnownProps = CommitKnownProps>(
  commits: Iterable<Commit> | AsyncIterable<Commit>,
  context?: Context<Commit>,
  options?: Options<Commit>
): Promise<string>;

function writeChangelogStream<Commit extends CommitKnownProps = CommitKnownProps>(
  context?: Context<Commit>,
  options?: Options<Commit>,
  includeDetails?: boolean
): Transform;

Changelog Writers

Commit Transformation

Functions for transforming and processing commit data with immutable safety and configurable transformation pipelines.

function transformCommit<Commit extends AnyObject, Args extends unknown[]>(
  commit: Commit,
  transform: ((commit: Commit, ...args: Args) => Partial<Commit> | null | Promise<Partial<Commit> | null>) | null | undefined,
  ...args: Args
): Promise<TransformedCommit<Commit> | null>;

function defaultCommitTransform<Commit extends CommitKnownProps = CommitKnownProps>(
  commit: Commit,
  _context: unknown,
  options: Pick<FinalOptions<Commit>, 'formatDate'>
): Partial<Commit>;

Utilities

Context and Options

Configuration interfaces for controlling changelog generation behavior, including commit grouping, sorting, template customization, and repository metadata.

interface Context<Commit extends CommitKnownProps = CommitKnownProps> {
  version?: string;
  isPatch?: boolean;
  title?: string;
  date?: string;
  linkReferences?: boolean;
  repository?: string;
  host?: string;
  owner?: string;
  // ... additional context properties
}

interface Options<Commit extends CommitKnownProps = CommitKnownProps> {
  groupBy?: keyof Commit;
  commitsSort?: SortBy<Commit>;
  transform?: CommitTransformFunction<Commit>;
  generateOn?: GenerateOnFunction<Commit> | keyof Commit | null;
  // ... additional options
}

Context and Options

Type Definitions

Complete TypeScript type definitions for commits, context, options, and all related interfaces.

interface CommitKnownProps {
  type?: string | null;
  header?: string | null;
  version?: string | null;
  hash?: string | null;
  committerDate?: string | null;
  notes: CommitNote[];
  revert?: AnyObject | null;
  body?: string | null;
  footer?: string | null;
}

interface Details<Commit extends CommitKnownProps = CommitKnownProps> {
  log: string;
  keyCommit: Commit | null;
}

Types

CLI Tool

Command-line interface for processing commit files and generating changelogs from the terminal.

# Process commits from file
conventional-changelog-writer commits.ldjson

# Process from stdin
cat commits.ldjson | conventional-changelog-writer

# With context and options files
conventional-changelog-writer -c context.json -o options.js commits.ldjson

The CLI accepts line-delimited JSON files containing commit objects and outputs formatted changelog text.