Configuration Reference

Customize TurboVersion's behavior through a version.config.json file or CLI arguments. Example minimal config:

{
  "tagPrefix": "v",
  "baseBranch": "main",
  "versionStrategy": "commitMessage"
}

Core Properties

🏷️ Versioning Strategy

Property	Type	Default	Description
`versionStrategy`	`"commitMessage"` \| `"branchPattern"`	`"commitMessage"`	How versions are calculated
`preset`	`"angular"` \| `"conventionalcommits"`	`"angular"`	Commit message convention style
`branchPattern`	`string[]`	`["major", "minor", "patch"]`	Branch prefixes that trigger bumps

Example Branch Pattern Config:

{
  "versionStrategy": "branchPattern",
  "branchPattern": ["release/", "feature/", "hotfix/"]
}

🔖 Tagging & Releases

Property	Type	Default	Description
`tagPrefix`	`string`	`"v"`	Prefix for Git tags (e.g., `pkg@1.0.0`)
`prereleaseIdentifier`	`string`	`null`	Prerelease tag (e.g., `beta`, `alpha`, `beta.${branchName}`)
`commitMessage`	`string`	`"chore(release): ${version} [skip-ci]"`	Template for release commits

Custom Tag Example:

{
  "tagPrefix": "pkg-",
  "prereleaseIdentifier": "beta.${branchName}"
}
// On feature/auth-flow, generates a tag like: pkg-1.0.0-beta-feature-auth-flow.0

prereleaseIdentifier supports ${branchName}, ${packageName}, and ${target} templates. Template output is sanitized into a SemVer-safe identifier, so beta.${branchName} on feature/auth-flow becomes beta-feature-auth-flow. ${branchName} is useful in prerelease pipelines because each feature branch gets its own prerelease stream instead of sharing one global beta.0, beta.1 sequence.

🧩 Monorepo Controls

Property	Type	Default	Description
`sync`	`boolean`	`false`	Whether all packages share versions
`updateInternalDependencies`	`"major"` \| `"minor"` \| `"patch"` \| `false`	`"patch"`	How to bump cross-package deps
`skip`	`string[]`	`[]`	Packages to exclude from versioning

Monorepo Example:

{
  "sync": false,
  "updateInternalDependencies": "minor",
  "skip": ["internal-utils"]
}

Advanced Properties

🔄 Git Integration

Property	Type	Default	Description
`baseBranch`	`string`	`"main"`	Branch to compare changes against
`skipHooks`	`boolean`	`false`	Bypass Git commit hooks
`analyzeCommitsSince`	`string`	`"last-release"`	Alternative: `"tag:v1.0.0"`

TurboVersion refreshes remote tags before calculating versions by running git fetch --tags --force origin. CI jobs should still use full checkout history so commit and tag analysis have the data they need:

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

⚠️ Validation Rules

Required Properties These must be defined in every config:

{
  "tagPrefix": "v",  // Required
  "baseBranch": "main"  // Required
}

Value Restrictions
- preset only accepts angular or conventionalcommits
- updateInternalDependencies requires semver level or false

Full Configuration Example

{
  "tagPrefix": "pkg@",
  "baseBranch": "develop",
  "versionStrategy": "commitMessage",
  "preset": "angular",
  "sync": false,
  "updateInternalDependencies": "minor",
  "prereleaseIdentifier": "rc",
  "skip": ["docs", "test-utils"],
  "commitMessage": "chore(release): ${packageName}@${version} [skip-ci]",
  "skipHooks": true
}

CLI Overrides

All properties can be set via command line:

turboversion bump \
  --tag-prefix="pkg@" \
  --prerelease-identifier="beta" \
  --skip="docs,test-utils"

Migration Tips

From Lerna/Changesets Set these equivalents:

{
  "tagPrefix": "${packageName}@",
  "updateInternalDependencies": "minor",
  "sync": false
}

Troubleshooting
- "Invalid config": Run turboversion validate to check errors
- "Unknown property": Ensure you're on the latest version

Configuration Schema