Turboversion 🚀

Automated Semantic Versioning for Monorepos and Single Packages

Turboversion is a powerful CLI tool that automates version bumps according to Semantic Versioning (SemVer). By analyzing your commit history or branch patterns, it intelligently determines version updates, saving you time and reducing human error in the versioning process.

Features

• ✅ Automatic version bumps based on commit messages or branch names
• ✅ Monorepo support with both sync and async versioning modes
• ✅ Semantic Versioning (SemVer) compliance
• ✅ Customizable through version.config.json
• ✅ PNPM workspace optimized
• ✅ Supports prerelease versions
• ✅ Skip specific packages when needed

Installation

# Using yarn
yarn add -D turboversion

# Using pnpm
pnpm add -D turboversion

# Using npm
npm install -D turboversion

Usage Modes

🔄 Sync Mode (Default)

In sync mode, all packages share the same version number. Ideal for tightly coupled packages.

Monorepo Example:

packages/
  pkg-a/ (1.0.0)
  pkg-b/ (1.0.0)
  pkg-c/ (1.0.0)

After feat commit → All become 1.1.0

Single Package: Updates the standalone package version.

Run with:

turboversion --bump [patch|minor|major]

🔀 Async Mode (Monorepos only)

Only updated packages get version bumps. Perfect for independent versioning.

Example:

packages/
  pkg-a/ (1.0.0) ← modified
  pkg-b/ (1.0.0)
  pkg-c/ (1.0.0) ← modified

After changes → pkg-a 1.0.1, pkg-c 1.1.0 (based on changes)

Run with:

turboversion --async

Versioning Strategies

1. Semantic Commit Messages (Default)

Turboversion analyzes commit messages to determine version bumps:

Commit Type	Version Bump	Example Message
fix	Patch	fix(button): correct color
feat	Minor	feat: add new component
Breaking	Major	feat!: remove deprecated API

Full type list:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test changes
• chore: Maintenance tasks

Example:

git commit -m "feat(button): add new button"

2. Branch Pattern Strategy

Alternative approach using branch names:

{
  "versionStrategy": "branchPattern",
  "branchPattern": ["major", "minor", "patch"]
}

Example: Merging a branch named minor will trigger a minor version bump.

Configuration (version.config.json)

Configure Turboversion to match your workflow:

{
  "tagPrefix": "v",
  "baseBranch": "main",
  "sync": false,
  "updateInternalDependencies": "patch",
  "skip": ["private-pkg"],
  "versionStrategy": "commitMessage",
  "branchPattern": ["major", "minor", "patch"],
  "prereleaseIdentifier": "beta",
  "skipHooks": false
}

Key Options:

Option	Description	Default
tagPrefix	Git tag prefix	v
baseBranch	Your main branch	main
sync	Sync versioning mode	false
versionStrategy	commitMessage or branchPattern	commitMessage
prereleaseIdentifier	Prerelease tag (e.g., beta)	-

PNPM Workflow (Recommended)

# 1. Update versions
pnpm turboversion

# 2. Publish all updated packages
pnpm publish -r

Command Reference

Global Options

• --help: Show help
• --version: Show version

Sync Mode Options

• -b, --bump: Version bump type (patch|minor|major|premajor|preminor|prepatch|prerelease)

Async Mode Options

• -t, --target: Specific package to bump
• -b, --bump: Force specific bump type

Why Turboversion?

⏱️ Saves time - No more manual version updates 🔒 Reduces errors - Automatic SemVer compliance 🤝 Improves collaboration - Clear version history 🧩 Monorepo optimized - Flexible versioning strategies ⚡ PNPM ready - Perfect workspace integration

Learn More

• Semantic Versioning
• Conventional Commits
• PNPM Workspaces