0
# Standard Version
1

2
Standard Version is a Node.js command-line tool that automates versioning and changelog generation for projects following the Conventional Commits specification. It provides a complete workflow for semantic versioning by analyzing commit messages to determine version bumps, automatically updating package.json and other metadata files, generating detailed changelogs using conventional-changelog, and creating git tags for releases.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const standardVersion = require('standard-version');
15
```
16

17
For CLI usage:
18
```bash
19
npx standard-version
20
# or globally: npm install -g standard-version
21
standard-version
22
```
23

24
## Basic Usage
25

26
### CLI Usage
27

28
```bash
29
# Standard release (analyzes commits and bumps version accordingly)
30
standard-version
31

32
# Specific release type
33
standard-version --release-as major
34
standard-version --release-as minor
35
standard-version --release-as patch
36

37
# Pre-release
38
standard-version --prerelease
39
standard-version --prerelease alpha
40

41
# First release
42
standard-version --first-release
43

44
# Dry run (see what would be done)
45
standard-version --dry-run
46
```
47

48
### Programmatic Usage
49

50
```javascript
51
const standardVersion = require('standard-version');
52

53
// Basic usage with default options
54
await standardVersion({});
55

56
// With custom options
57
await standardVersion({
58
  releaseAs: 'minor',
59
  infile: 'CHANGELOG.md',
60
  silent: false,
61
  dryRun: true
62
});
63
```
64

65
## Architecture
66

67
Standard Version is built around several key components:
68

69
- **CLI Interface**: Command-line parser with comprehensive option support via yargs
70
- **Core Workflow**: Orchestrates bump, changelog, commit, and tag lifecycles
71
- **File Updater System**: Pluggable system for updating version in different file formats (JSON, plain text, custom)
72
- **Lifecycle Hooks**: Pre/post hooks for each stage (prebump, precommit, etc.)
73
- **Configuration System**: Support for multiple configuration file formats
74
- **Conventional Changelog Integration**: Uses conventional-changelog for changelog generation
75

76
## Capabilities
77

78
### Command Line Interface
79

80
Complete CLI tool with comprehensive option support for automated versioning workflows. Supports both interactive and CI/CD usage patterns.
81

82
```bash { .api }
83
# Core CLI options
84
standard-version [options]
85

86
--release-as, -r <release-type>     # major|minor|patch or specific version
87
--prerelease, -p [tag]             # Make pre-release with optional tag
88
--first-release, -f                # Mark as first release
89
--dry-run                          # Preview changes without executing
90
--silent                           # Suppress output
91
--sign, -s                         # Sign git commit and tag
92
--no-verify, -n                    # Bypass git hooks
93
--tag-prefix, -t <prefix>          # Custom git tag prefix (default: 'v')
94
```
95

96
[Command Line Interface](./cli.md)
97

98
### Programmatic API
99

100
Node.js API for integrating standard-version into build scripts and automation workflows.
101

102
```javascript { .api }
103
/**
104
 * Main function for programmatic usage
105
 * @param {Object} argv - Configuration options object
106
 * @returns {Promise<void>} Promise that resolves when process completes
107
 */
108
async function standardVersion(argv);
109
```
110

111
[Programmatic API](./api.md)
112

113
### Configuration System
114

115
Flexible configuration system supporting multiple file formats and package.json integration.
116

117
```javascript { .api }
118
/**
119
 * Load configuration from standard-version config files
120
 * @returns {Object} Configuration object
121
 */
122
function getConfiguration();
123
```
124

125
[Configuration](./configuration.md)
126

127
### File Updater System
128

129
Pluggable system for updating version numbers in different file formats with support for custom updaters.
130

131
```javascript { .api }
132
/**
133
 * Resolve updater from file path or configuration object
134
 * @param {string|Object} arg - File path or updater configuration
135
 * @returns {Object|false} Updater object or false if invalid
136
 */
137
function resolveUpdaterObjectFromArgument(arg);
138

139
interface Updater {
140
  readVersion(contents: string): string;
141
  writeVersion(contents: string, version: string): string;
142
  isPrivate?(contents: string): boolean;
143
}
144
```
145

146
[File Updaters](./updaters.md)
147

148
### Lifecycle Management
149

150
Complete lifecycle management with hooks for customizing the versioning workflow at each stage.
151

152
```javascript { .api }
153
/**
154
 * Execute lifecycle script for given hook
155
 * @param {Object} args - Configuration object
156
 * @param {string} hookName - Name of lifecycle hook
157
 * @returns {Promise<string>} Promise resolving to script output
158
 */
159
async function runLifecycleScript(args, hookName);
160
```
161

162
[Lifecycle Hooks](./lifecycle.md)
163

164
## Types
165

166
```javascript { .api }
167
interface StandardVersionOptions {
168
  // Release configuration
169
  releaseAs?: string;              // Release type or specific version
170
  prerelease?: string | boolean;   // Pre-release tag or true for default
171
  firstRelease?: boolean;          // Mark as first release
172
  
173
  // File configuration
174
  infile?: string;                 // Changelog file path (default: 'CHANGELOG.md')
175
  packageFiles?: string[];         // Files to read version from
176
  bumpFiles?: string[];           // Files to update with new version
177
  
178
  // Git configuration
179
  sign?: boolean;                  // Sign git commit and tag
180
  noVerify?: boolean;              // Bypass git hooks
181
  commitAll?: boolean;             // Commit all staged changes
182
  tagPrefix?: string;              // Git tag prefix (default: 'v')
183
  
184
  // Behavior configuration
185
  silent?: boolean;                // Suppress output
186
  dryRun?: boolean;               // Preview mode without changes
187
  gitTagFallback?: boolean;        // Use git tags if no package file found
188
  
189
  // Advanced configuration
190
  scripts?: Record<string, string>; // Lifecycle hook scripts
191
  skip?: Record<string, boolean>;   // Skip specific steps
192
  preset?: string;                  // Conventional changelog preset
193
  path?: string;                   // Only include commits under path
194
  lernaPackage?: string;           // Package name for Lerna monorepo tag extraction
195
  header?: string;                 // Custom changelog header
196
  releaseCommitMessageFormat?: string; // Custom commit message template
197
}
198

199
interface ValidationSchema {
200
  scripts?: Record<string, string>;
201
  skip?: Record<string, boolean>;
202
}
203
```