🧑‍🍳 TurboVersion Recipes

Starter Kits

1. Single-Package Repository

{
  "tagPrefix": "v",
  "baseBranch": "main",
  "changelog": {
    "header": "# Changelog\n\nAll notable changes\n"
  }
}

When to use: Simple JS libraries or apps Features:

Standard semantic versioning
Basic changelog generation

2. Monorepo (Independent Versions)

{
  "sync": false,
  "tagPrefix": "${packageName}@",
  "updateInternalDependencies": "minor",
  "skip": ["docs", "examples"]
}

When to use:

Component libraries
Microservices with separate release cycles

3. Monorepo (Lockstep Versions)

{
  "sync": true,
  "tagPrefix": "release-",
  "commitMessage": "chore(release): v${version} [skip-ci]"
}

When to use:

Full-stack applications
Tightly coupled packages

CI/CD Integrations

GitHub Actions

name: Release
on:
  push:
    branches: [main]

jobs:
  version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for commit analysis

      - name: Version Packages
        run: |
          npx turboversion
          git config user.name "GitHub Actions"
          git config user.email "actions@github.com"
          git push --follow-tags

GitLab CI

release_job:
  image: node:18
  script:
    - npm install -g turboversion
    - turboversion
    - git push origin HEAD --follow-tags
  only:
    - main

Advanced Patterns

1. Prerelease Pipeline

{
  "prereleaseIdentifier": "beta.${branchName}",
  "branchPattern": ["release/"],
  "commitMessage": "chore(beta): v${version}"
}

Workflow:

git checkout -b release/v2
turboversion --prerelease

Using ${branchName} keeps prerelease tags from different branches out of the same sequence. For example, feature/auth-flow and feature/search can create independent prerelease tags instead of both competing for v1.1.0-beta.0.

2. Custom Changelog Groups

{
  "changelog": {
    "groups": [
      {
        "title": "🚀 Features",
        "types": ["feat"],
        "labels": ["feature"]
      },
      {
        "title": "🛠️ Maintenance",
        "types": ["chore", "refactor"]
      }
    ]
  }
}

3. Enterprise Monorepo

{
  "sync": false,
  "tagPrefix": "pkg-",
  "analyzeCommitsSince": "last-week",
  "updateInternalDependencies": false
}

Migration Recipes

From Lerna

# package.json
{
  "scripts": {
-   "version": "lerna version",
+   "version": "turboversion"
  }
}

From Changesets

Remove .changesets folder
Add config:

{
  "preset": "conventionalcommits",
  "commitMessage": "chore(release): ${packageName}@${version}"
}

Troubleshooting Recipes

❌ Problem: Dependent packages not updating Solution: Increase dependency bump level:

{
  "updateInternalDependencies": "minor"
}

❌ Problem: Slow analysis in large repos Solution: Limit commit history:

{
  "analyzeCommitsSince": "last-month"
}

TurboVersion Recipes

On this page