turborepo-template-upgrade

Seamlessly keep your repo in sync with turborepo-template.

🚀 Purpose

turborepo-template-upgrade is a small utility built for repositories that were bootstrapped using react18-tools/turborepo-template.

Instead of manually copy-pasting template updates (bug fixes, CI improvements, tooling upgrades), this package provides:

• One command upgrade – pull changes from the template into your repo.
• Safe patching – applies diffs instead of overwriting.
• Smart conflict resolution – especially for root package.json file.

---

📦 Installation

You don’t need to add this as a runtime dependency. Use it as a dev tool:

npm install -D turborepo-template-upgrade
# or
yarn add -D turborepo-template-upgrade

---

⚡ Usage

Inside a repo created with turborepo-template:

npx turborepo-template-upgrade

We just released a shorthand -- pnpx tt-upgrade

CLI Options

# Basic usage with debug logging
npx turborepo-template-upgrade --debug

# Preview changes without applying
npx turborepo-template-upgrade --dry-run

# Skip dependency installation
npx turborepo-template-upgrade --skip-install

# Exclude specific paths
npx turborepo-template-upgrade --exclude "docs,examples"

# Upgrade from specific commit, tag, or branch
npx turborepo-template-upgrade --from v1.2.3
npx turborepo-template-upgrade --from abc123def
npx turborepo-template-upgrade --from feature-branch

Available Options:

• --debug / -d - Enable detailed logging
• --dry-run - Preview changes without applying
• --template-url <url> - Custom template repository URL
• --exclude <paths> - Comma-separated paths to exclude
• --skip-install - Skip dependency reinstallation
• --remote-name <name> - Custom git remote name
• --max-retries <num> - Maximum patch retry attempts
• --skip-clean-check - Skip git tree clean validation
• --from <ref> - Specific commit hash, tag, or branch to upgrade from
• --last-commit-file <file> / -l <file> - Custom file to store/load last commit hash
• --init [file] / -i [file] - Create default config file (optionally specify filename)
• --config <file> / -c <file> - Use custom config file
• --help / -h - Show help message

This will:

1. Fetch the latest changes from the template repo.
2. Compute a git diff since your last upgrade.
3. Apply the patch on top of your repo.
4. Attempt to auto-resolve package.json conflicts.
5. Store the last applied commit in .turborepo-template.lst.

If there are remaining conflicts, you’ll see them in .template.patch.

---

⚠️ Important Migration Notice

Biome Migration: The turborepo-template has migrated from ESLint + Prettier to Biome for linting and formatting. If you prefer to continue using ESLint + Prettier, configure your upgrade to use the legacy branch:

See discussion here: react18-tools/turborepo-template#69

npx turborepo-template-upgrade --template-url https://github.com/react18-tools/turborepo-template --from legacy/eslint-prettier

Or add to your .tt-upgrade.config.json:

{
  "templateUrl": "https://github.com/react18-tools/turborepo-template",
  "from": "legacy/eslint-prettier"
}

---

🔧 Configuration

Create .tt-upgrade.config.json in your repo root for persistent settings:

{
  "debug": false,
  "skipInstall": true,
  "excludePaths": ["docs", "examples"],
  "templateUrl": "https://github.com/custom/template",
  "remoteName": "upstream",
  "maxPatchRetries": 5,
  "from": "v1.2.3",
  "lastCommitFile": ".my-template.lst"
}

CLI options override config file settings.

---

🧩 Conflict Resolution

• package.json merges are handled automatically:
  • Keeps your dependencies.
  • Brings in template upgrades.
  • Deduplicates versions.
• For other files, standard git apply --3way conflict markers may appear.

---

🔍 Example Workflows

Basic Upgrade

# 1. Upgrade with debug logging
npx turborepo-template-upgrade --debug

# 2. Review conflicts (if any)
git status
cat .template.patch

# 3. Commit changes
git add .
git commit -m "chore: upgrade template"

Preview Mode

# Preview what would change
npx turborepo-template-upgrade --dry-run

# Apply if satisfied
npx turborepo-template-upgrade

Custom Configuration

# Skip installation and exclude docs
npx turborepo-template-upgrade --skip-install --exclude "docs,examples"

# Upgrade from specific version
npx turborepo-template-upgrade --from v2.1.0

# Use legacy ESLint + Prettier setup
npx turborepo-template-upgrade --from legacy/eslint-prettier

# Create config file
npx turborepo-template-upgrade --init
npx turborepo-template-upgrade --init my-config.json

# Use custom last commit file
npx turborepo-template-upgrade --last-commit-file .my-template.lst

---

🛠 How It Works

• Template repo is added as a Git remote (template).
• Last applied commit hash is tracked in .turborepo-template.lst.
• git diff between last applied commit → template/main.
• Patch applied locally with git apply --3way.

---

🙏 Acknowledgments

Thanks to the react18-tools community for shaping the turborepo ecosystem.

License

This library is licensed under the MPL-2.0 open-source license.

Please enroll in our courses or sponsor our work.

---

with 💖 by Mayank Kumar Chaudhari