@releasekit/version
v0.47.0
Published
Semantic versioning based on Git history and conventional commits
Maintainers
Readme
@releasekit/version
[!WARNING] 🚧 Pre-1.0.0 — ReleaseKit is evolving fast and 💥 breaking changes are common; it's not production-ready until
v1.0.0. Pin exact versions. See the main README for details.
Semantic versioning based on Git history and conventional commits.
Features
- Conventional commits — automatic version bumps from commit history (
feat:→ minor,fix:→ patch,BREAKING CHANGE→ major) - Monorepo support — sync, single, or independent (async) versioning strategies
- npm and Rust — updates both
package.jsonandCargo.tomlmanifests - Branch patterns — determine bumps from branch names (e.g.
feature/*→ minor) - Package targeting — version specific packages with
--target - Prerelease support — create alpha, beta, or custom prerelease versions
- Dry-run mode — preview changes without modifying files or creating tags
- JSON output — structured results for piping to
@releasekit/notesand CI scripts - Package-specific tags — configurable tag templates per package
Installation
npm:
npm install -g @releasekit/versionpnpm:
pnpm add -g @releasekit/versionNote: This package is ESM only and requires Node.js 22.12+.
Quick Start
# Auto-detect bump from conventional commits
releasekit-version
# Force a specific bump type
releasekit-version --bump minor
# Preview without side effects
releasekit-version --dry-run --json
# Target specific packages in a monorepo
releasekit-version --target @scope/core,@scope/cli
# Create a prerelease
releasekit-version --prerelease betaCLI Reference
Flags are in the CLI reference.
JSON Output
With --json (or --output <file>), the result is wrapped in the uniform CLI envelope: status, changed, warnings, and errors sit alongside the payload, and the version data itself is at data:
{
"schemaVersion": 1,
"status": "success",
"changed": false,
"data": {
"dryRun": true,
"updates": [
{
"packageName": "@scope/core",
"newVersion": "1.2.3",
"filePath": "/path/to/package.json"
}
],
"changelogs": [
{
"packageName": "@scope/core",
"version": "1.2.3",
"previousVersion": "v1.2.2",
"revisionRange": "v1.2.2..HEAD",
"repoUrl": "https://github.com/org/repo",
"entries": [
{ "type": "added", "description": "New feature" },
{ "type": "fixed", "description": "Bug fix" }
]
}
],
"commitMessage": "chore: release v1.2.3",
"tags": ["v1.2.3"]
},
"warnings": [],
"errors": []
}@releasekit/notes and @releasekit/publish unwrap the envelope on input, so their --input and stdin accept this output directly (a bare data object is still accepted too). A script reading the output itself should read .data — for example jq '.data.updates[]'. On failure, status is "error", data is null, and errors[] carries a machine-readable code.
Configuration
Configure via releasekit.config.json:
{
"version": {
"preset": "conventionalcommits",
"versionPrefix": "v",
"tagTemplate": "${prefix}${version}",
"commitMessage": "chore: release ${packageName} v${version}",
"sync": true,
"packages": ["@mycompany/*"],
"skip": ["docs", "e2e"],
"mainPackage": "primary-package",
"packageSpecificTags": false,
"strictReachable": false,
"cargo": {
"enabled": true,
"paths": ["crates/"]
}
}
}Every version.* key and its default is in the configuration reference.
Using in CI
A few things to keep in mind when running releasekit-version in a pipeline:
- Always pass
fetch-depth: 0on checkout — the tool reads git history to determine the version bump and will produce incorrect results on a shallow clone. - Use
--jsonor--output <file>for reliable downstream parsing. Text output format can change; the JSON envelope'sschemaVersionchanges only on a breaking change to its shape. NO_COLOR=1disables ANSI colour codes in log output. Most CI environments setCI=trueautomatically, which the tool detects and adjusts for.
If you are running the full release pipeline (version + changelog + publish), use @releasekit/release instead of invoking releasekit-version directly. See the CI setup guide.
Programmatic API
@releasekit/version can be used as a library in Node.js code. The main entry point is VersionEngine.
import {
loadConfig,
VersionEngine,
enableJsonOutput,
getJsonData,
} from '@releasekit/version';
import type { VersionOutput, VersionRunOptions } from '@releasekit/version';
// 1. Load config from releasekit.config.json
const config = loadConfig({ cwd: '/path/to/project' });
// 2. Describe runtime overrides (none of these mutate the config object)
const runOptions: VersionRunOptions = {
bump: 'minor', // force bump type
dryRun: true, // preview only
targets: ['pkg-a'], // limit to specific packages
};
// 3. Enable JSON capture so getJsonData() has results to return
enableJsonOutput(runOptions.dryRun);
// 4. Run the engine
const engine = new VersionEngine(config, runOptions);
const packages = await engine.getWorkspacePackages();
await engine.run(packages);
// 5. Retrieve the structured output
const output: VersionOutput = getJsonData();
// output.updates — packages that received a version bump
// output.changelogs — per-package changelog entries
// output.tags — git tags that were (or would be) createdVersionRunOptions
All fields are optional. These are applied on top of the loaded config without mutating it.
| Field | Type | Description |
|-------|------|-------------|
| bump | 'major' \| 'minor' \| 'patch' | Force a specific bump type |
| prerelease | string \| boolean | Create a prerelease; true uses the configured identifier, a string overrides it |
| stable | boolean | Graduate prerelease packages to stable; skip already-stable ones (unless bump is also set) |
| dryRun | boolean | Preview only — no files written, no git operations |
| sync | boolean | Version all packages together at the same version |
| targets | string[] | Limit processing to these package name patterns |
VersionOutput
The output type is also exported from @releasekit/core:
import type { VersionOutput } from '@releasekit/version';Pass the result directly to versionOutputToChangelogInput from @releasekit/notes to generate changelogs without serialising to JSON.
Documentation
Acknowledgements
Originally forked from and inspired by jucian0/turbo-version.
License
MIT
