0
# Standard Changelog
1

2
Standard Changelog provides an opinionated approach to CHANGELOG generation using Angular commit conventions. It offers both a command-line interface and a JavaScript API for generating changelogs from git metadata, with automatic detection of features, fixes, performance improvements, and breaking changes.
3

4
## Package Information
5

6
- **Package Name**: standard-changelog
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install standard-changelog`
10

11
## Core Imports
12

13
```typescript
14
import { StandardChangelog } from "standard-changelog";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { StandardChangelog } = require("standard-changelog");
21
```
22

23
## Basic Usage
24

25
### CLI Usage
26

27
```bash
28
# Generate changelog for current release
29
standard-changelog
30

31
# Generate changelog for first release
32
standard-changelog --first-release
33

34
# Output to stdout
35
standard-changelog --stdout
36

37
# Append to existing changelog
38
standard-changelog -a
39
```
40

41
### API Usage
42

43
```typescript
44
import { StandardChangelog } from "standard-changelog";
45

46
// Basic usage
47
const generator = new StandardChangelog(process.cwd())
48
  .readPackage();
49

50
// Generate as stream
51
generator.writeStream().pipe(process.stdout);
52

53
// Generate as async iterator
54
for await (const chunk of generator.write()) {
55
  console.log(chunk);
56
}
57
```
58

59
## Architecture
60

61
Standard Changelog is built on top of the conventional-changelog ecosystem with these key components:
62

63
- **StandardChangelog Class**: Extends ConventionalChangelog with Angular preset pre-configured
64
- **CLI Interface**: Command-line tool with comprehensive flag support
65
- **Re-exported APIs**: Full access to underlying conventional-changelog functionality
66
- **Angular Preset**: Pre-configured commit convention parser following Angular guidelines
67

68
## Capabilities
69

70
### StandardChangelog Class
71

72
Core changelog generation class with Angular commit conventions pre-configured. Extends ConventionalChangelog with all inherited methods available.
73

74
```typescript { .api }
75
class StandardChangelog extends ConventionalChangelog {
76
  constructor(cwdOrGitClient: string | ConventionalGitClient);
77
}
78
```
79

80
[StandardChangelog API](./standard-changelog-api.md)
81

82
### CLI Interface
83

84
Command-line interface for generating changelogs with extensive configuration options.
85

86
```typescript { .api }
87
function runProgram(
88
  generator: ConventionalChangelog,
89
  flags: Flags
90
): Promise<void>;
91

92
interface Flags {
93
  infile?: string;
94
  outfile?: string;
95
  stdout?: boolean;
96
  preset?: string;
97
  pkg?: string;
98
  append?: boolean;
99
  releaseCount?: number;
100
  skipUnstable?: boolean;
101
  outputUnreleased?: boolean;
102
  verbose?: boolean;
103
  config?: string;
104
  context?: string;
105
  firstRelease?: boolean;
106
  lernaPackage?: string;
107
  tagPrefix?: string;
108
}
109
```
110

111
[CLI Interface](./cli-interface.md)
112

113
### Re-exported Types and Functions
114

115
All types and functions from conventional-changelog are re-exported for full ecosystem compatibility.
116

117
```typescript { .api }
118
// Core classes
119
export { ConventionalChangelog } from "conventional-changelog";
120

121
// Core types
122
export type {
123
  Commit,
124
  Package,
125
  Logger,
126
  PackageTransform,
127
  CommitTransformFunction,
128
  HostType,
129
  HostedGitInfo,
130
  HostOptions,
131
  FinalizedContext,
132
  Preset,
133
  Options,
134
  Params
135
} from "conventional-changelog";
136

137
// Utility functions
138
export { packagePrefix, flags, runProgram } from "conventional-changelog";
139
```
140

141
## Core Types
142

143
```typescript { .api }
144
interface ConventionalGitClient {
145
  cwd: string;
146
  debug?: Logger;
147
  getSemverTags(params?: GetSemverTagsParams): AsyncGenerator<string>;
148
  getCommits(params: GetCommitsParams, parserOptions?: ParserStreamOptions): AsyncGenerator<Commit>;
149
  verify(revision: string): Promise<void>;
150
  getConfig(key: string): Promise<string>;
151
}
152

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

155
interface Commit extends CommitBase {
156
  [key: string]: string | null;
157
}
158

159
interface CommitBase {
160
  merge: string | null;
161
  revert: CommitMeta | null;
162
  header: string | null;
163
  body: string | null;
164
  footer: string | null;
165
  notes: CommitNote[];
166
  mentions: string[];
167
  references: CommitReference[];
168
}
169

170
interface CommitNote {
171
  title: string;
172
  text: string;
173
}
174

175
interface CommitReference {
176
  raw: string;
177
  action: string | null;
178
  owner: string | null;
179
  repository: string | null;
180
  issue: string;
181
  prefix: string;
182
}
183

184
type CommitMeta = Record<string, string | null>;
185

186
interface Details<T> {
187
  log: string;
188
  keyCommit: T | null;
189
}
190
```