0
# Configuration
1

2
Standard Version supports flexible configuration through multiple file formats and package.json integration. Configuration allows customization of versioning behavior, lifecycle hooks, file handling, and integration with conventional changelog presets.
3

4
## Capabilities
5

6
### Configuration File Loading
7

8
Automatic discovery and loading of configuration from standard locations.
9

10
```javascript { .api }
11
/**
12
 * Load and merge configuration from all available sources
13
 * @returns {Object} Merged configuration object
14
 * @throws {Error} If configuration file contains invalid format or structure
15
 */
16
function getConfiguration();
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const { getConfiguration } = require('standard-version/lib/configuration');
23

24
// Load configuration automatically
25
const config = getConfiguration();
26
console.log('Active configuration:', config);
27

28
// Configuration is loaded from first found file:
29
// 1. .versionrc
30
// 2. .versionrc.cjs  
31
// 3. .versionrc.json
32
// 4. .versionrc.js
33
// 5. package.json (under "standard-version" key)
34
```
35

36
### Configuration File Formats
37

38
Standard Version supports multiple configuration file formats for different project needs.
39

40
**JSON Configuration (`.versionrc`, `.versionrc.json`):**
41

42
```json { .api }
43
{
44
  "tagPrefix": "v",
45
  "releaseCommitMessageFormat": "chore(release): {{currentTag}}",
46
  "scripts": {
47
    "prebump": "echo 'Starting version bump'",
48
    "postbump": "npm run build",
49
    "precommit": "npm run test",
50
    "posttag": "npm publish"
51
  },
52
  "skip": {
53
    "changelog": false,
54
    "tag": false
55
  },
56
  "packageFiles": [
57
    "package.json",
58
    "manifest.json"
59
  ],
60
  "bumpFiles": [
61
    "package.json",
62
    "manifest.json",
63
    "version.txt"
64
  ],
65
  "infile": "CHANGELOG.md",
66
  "header": "# Release Notes\n\nAll notable changes will be documented in this file.\n"
67
}
68
```
69

70
**JavaScript Configuration (`.versionrc.js`, `.versionrc.cjs`):**
71

72
```javascript { .api }
73
// .versionrc.js - ES modules
74
export default {
75
  tagPrefix: 'release-',
76
  scripts: {
77
    prebump: 'npm run validate',
78
    postbump: process.env.CI ? 'npm run build:prod' : 'npm run build:dev'
79
  },
80
  skip: {
81
    changelog: process.env.SKIP_CHANGELOG === 'true',
82
    tag: process.env.DRY_RUN === 'true'
83
  }
84
};
85

86
// .versionrc.cjs - CommonJS
87
module.exports = {
88
  tagPrefix: 'v',
89
  scripts: {
90
    prebump: 'npm run lint && npm run test',
91
    postbump: 'npm run build'
92
  }
93
};
94

95
// Function-based configuration
96
module.exports = function() {
97
  return {
98
    tagPrefix: process.env.TAG_PREFIX || 'v',
99
    silent: process.env.CI === 'true',
100
    dryRun: process.env.DRY_RUN === 'true'
101
  };
102
};
103
```
104

105
**Package.json Integration:**
106

107
```json { .api }
108
{
109
  "name": "my-package", 
110
  "version": "1.0.0",
111
  "standard-version": {
112
    "tagPrefix": "v",
113
    "scripts": {
114
      "prebump": "npm run test",
115
      "postbump": "npm run build"
116
    },
117
    "skip": {
118
      "changelog": false
119
    }
120
  }
121
}
122
```
123

124
### Core Configuration Options
125

126
Essential configuration options for controlling standard-version behavior.
127

128
```javascript { .api }
129
interface CoreConfiguration {
130
  // Version and release configuration
131
  tagPrefix?: string;                    // Prefix for git tags (default: 'v')
132
  releaseCommitMessageFormat?: string;   // Template for release commit message
133
  firstRelease?: boolean;                // Skip version bump for initial release
134
  
135
  // File handling configuration
136
  infile?: string;                       // Changelog file path (default: 'CHANGELOG.md')
137
  packageFiles?: string[];               // Files to read version from
138
  bumpFiles?: string[];                 // Files to update with new version
139
  
140
  // Behavior configuration
141
  silent?: boolean;                      // Suppress output messages
142
  dryRun?: boolean;                     // Preview changes without executing
143
  gitTagFallback?: boolean;              // Use git tags if no package files found
144
  
145
  // Git configuration
146
  sign?: boolean;                        // Sign commits and tags with GPG
147
  noVerify?: boolean;                   // Bypass git hooks during commit
148
  commitAll?: boolean;                   // Commit all staged changes
149
}
150
```
151

152
**Usage Examples:**
153

154
```json
155
{
156
  "tagPrefix": "release-",
157
  "releaseCommitMessageFormat": "build: release {{currentTag}}",
158
  "infile": "HISTORY.md",
159
  "packageFiles": ["package.json", "pyproject.toml"],
160
  "bumpFiles": ["package.json", "pyproject.toml", "VERSION"],
161
  "silent": false,
162
  "dryRun": false,
163
  "gitTagFallback": true,
164
  "sign": true,
165
  "noVerify": false,
166
  "commitAll": false
167
}
168
```
169

170
### Lifecycle Hook Scripts
171

172
Configure custom scripts to run at different stages of the release process.
173

174
```javascript { .api }
175
interface LifecycleScripts {
176
  prebump?: string;      // Before version calculation and file updates
177
  postbump?: string;     // After version bump but before changelog
178
  prechangelog?: string; // Before changelog generation
179
  postchangelog?: string;// After changelog generation but before commit
180
  precommit?: string;    // Before git commit
181
  postcommit?: string;   // After git commit but before tag
182
  pretag?: string;       // Before git tag creation
183
  posttag?: string;      // After git tag creation (final step)
184
}
185
```
186

187
**Usage Examples:**
188

189
```json
190
{
191
  "scripts": {
192
    "prebump": "npm run lint && npm run test",
193
    "postbump": "npm run build",
194
    "prechangelog": "echo 'Generating changelog...'",
195
    "postchangelog": "npm run format-changelog",
196
    "precommit": "npm run security-check",
197
    "postcommit": "echo 'Changes committed successfully'",
198
    "pretag": "npm run validate-tag",
199
    "posttag": "npm publish && npm run deploy-docs"
200
  }
201
}
202
```
203

204
### Step Skipping Configuration
205

206
Configure which steps of the release process to skip.
207

208
```javascript { .api }
209
interface SkipConfiguration {
210
  bump?: boolean;        // Skip version calculation and file updates
211
  changelog?: boolean;   // Skip changelog generation
212
  commit?: boolean;      // Skip git commit creation
213
  tag?: boolean;         // Skip git tag creation
214
}
215
```
216

217
**Usage Examples:**
218

219
```json
220
{
221
  "skip": {
222
    "bump": false,
223
    "changelog": false,
224
    "commit": false,
225
    "tag": false
226
  }
227
}
228
```
229

230
### Advanced Configuration Options
231

232
Extended configuration for complex workflows and integrations.
233

234
```javascript { .api }
235
interface AdvancedConfiguration {
236
  // Conventional changelog configuration
237
  preset?: string;                       // Changelog preset name
238
  header?: string;                       // Custom changelog header
239
  path?: string;                         // Only include commits under path
240
  
241
  // Custom updater configuration
242
  updaters?: Array<{
243
    filename: string;
244
    type?: 'json' | 'plain-text';
245
    updater?: string | UpdaterObject;
246
  }>;
247
  
248
  // Git configuration
249
  gitTagFallback?: boolean;              // Fallback to git tags for version
250
  commitAll?: boolean;                   // Commit all changes, not just version files
251
}
252

253
interface UpdaterObject {
254
  readVersion(contents: string): string;
255
  writeVersion(contents: string, version: string): string;
256
  isPrivate?(contents: string): boolean;
257
}
258
```
259

260
**Usage Examples:**
261

262
```json
263
{
264
  "preset": "angular",
265
  "header": "# Changelog\n\nAll notable changes documented here.\n",
266
  "path": "packages/core",
267
  "updaters": [
268
    {
269
      "filename": "version.py",
270
      "type": "plain-text"
271
    },
272
    {
273
      "filename": "Cargo.toml",
274
      "updater": "./scripts/cargo-updater.js"
275
    }
276
  ]
277
}
278
```
279

280
### Environment Variable Integration
281

282
Configuration can be influenced by environment variables in JavaScript config files.
283

284
```javascript { .api }
285
// .versionrc.js
286
export default {
287
  silent: process.env.CI === 'true',
288
  dryRun: process.env.DRY_RUN === 'true',
289
  tagPrefix: process.env.TAG_PREFIX || 'v',
290
  scripts: {
291
    prebump: process.env.SKIP_TESTS === 'true' ? '' : 'npm test',
292
    posttag: process.env.AUTO_PUBLISH === 'true' ? 'npm publish' : ''
293
  },
294
  skip: {
295
    tag: process.env.SKIP_TAGGING === 'true',
296
    changelog: process.env.SKIP_CHANGELOG === 'true'
297
  }
298
};
299
```
300

301
### Configuration Validation
302

303
Standard Version validates configuration format and throws descriptive errors for invalid configurations.
304

305
```javascript { .api }
306
/**
307
 * Configuration validation rules:
308
 * - scripts must be an object (not array or primitive)
309
 * - skip must be an object (not array or primitive)
310
 * - JavaScript configs must export object or function returning object
311
 * - Function configs are called with no arguments
312
 */
313
```
314

315
**Common Validation Errors:**
316

317
```javascript
318
// Invalid configuration examples that will throw errors:
319

320
// ❌ scripts as array
321
{ "scripts": ["prebump", "postbump"] }
322

323
// ❌ skip as string  
324
{ "skip": "changelog,tag" }
325

326
// ❌ JavaScript config returning non-object
327
module.exports = "invalid";
328

329
// ✅ Valid configurations
330
{ "scripts": { "prebump": "npm test" } }
331
{ "skip": { "changelog": true } }
332
module.exports = { tagPrefix: "v" };
333
```
334

335
## Configuration Priority
336

337
Configuration is loaded and merged in the following order (later sources override earlier ones):
338

339
1. Built-in defaults
340
2. Conventional changelog config spec defaults
341
3. Configuration file (first found: `.versionrc`, `.versionrc.cjs`, `.versionrc.json`, `.versionrc.js`)
342
4. `package.json` "standard-version" key
343
5. Command-line arguments (CLI only)
344
6. Programmatic options (API only)