Claude Code & Turborepo: Monorepos effizient verwalten

Wer mehrere zusammenhängende Pakete in einem Repository verwaltet, kennt das Problem: Build-Zeiten explodieren, Abhängigkeiten werden unübersichtlich, und CI läuft unnötig lang, weil jedes Paket einzeln geprüft wird — auch wenn sich seit dem letzten Run nichts daran geändert hat. Turborepo löst genau das: intelligentes Task-Scheduling, inkrementelles Caching und Parallelisierung aus einer einzigen Konfigurationsdatei heraus.

Kombiniert mit Claude Code wird Monorepo-Entwicklung nicht nur schneller, sondern auch einfacher zu verstehen. Dieser Artikel zeigt, wie Turborepo funktioniert, wie es sich gegen Alternativen schlägt, und wo Claude Code konkret hilft — von der Pipeline-Konfiguration bis zur GitHub-Actions-Integration.

1. Was ist Turborepo?

Turborepo ist ein Build-System für JavaScript- und TypeScript-Monorepos, entwickelt von Vercel und seit Ende 2021 Open Source. Das Kernprinzip: Turborepo versteht die Abhängigkeiten zwischen deinen Workspace-Paketen und entscheidet daraus, welche Tasks in welcher Reihenfolge und parallel ausgeführt werden können.

Dazu kommt ein aggressives Caching-System. Turborepo speichert die Ausgabe jedes Tasks zusammen mit einem Hash der Eingaben: Source-Dateien, Umgebungsvariablen, Konfiguration. Hat sich nichts geändert, wird der Task beim nächsten Lauf nicht wiederholt — das Ergebnis aus dem Cache wird direkt wiederverwendet. Das klingt simpel, spart in der Praxis aber Minuten pro CI-Run.

2. Turborepo vs. Nx und Lerna

Der Monorepo-Markt hat mehrere etablierte Tools. Die ehrliche Einordnung:

• Lerna war lange der Standard, ist aber primär ein Release- und Versions-Tool — kein Build-System. Es orchestriert keine Tasks intelligent und hat kein natives Caching. Wird heute oft zusammen mit Nx eingesetzt.
• Nx ist mächtiger als Turborepo: Plugins für React, Angular, Next.js, NestJS und mehr, ein Dependency-Graph-Visualizer und eine eigene Cloud-Plattform. Der Preis ist Komplexität — Nx hat eine steilere Lernkurve und deutlich mehr Konfiguration.
• Turborepo macht eine Sache sehr gut: schnelle, einfache Task-Orchestrierung mit Caching. Kein Plugin-System, keine Framework-Opinions. Ideal für Teams, die schnell starten wollen ohne sich in Konfiguration zu verlieren.

Faustregel: Turborepo für neue Projekte und kleinere Teams, Nx wenn du ein bestehendes großes Monorepo migrieren oder tief in Framework-Integration investieren willst.

3. turbo.json: Die Pipeline-Konfiguration

Alles beginnt mit einer einzigen Datei im Root deines Repos: turbo.json. Hier definierst du, welche Tasks existieren, von welchen anderen Tasks sie abhängen, und was gecacht werden soll.

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "dist/**"]
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "lint": {
      "outputs": []
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

Das ^-Präfix bei "^build" ist entscheidend: Es bedeutet, dass zuerst alle Abhängigkeiten des aktuellen Pakets gebaut werden müssen — in der richtigen Reihenfolge, automatisch. Ohne Turborepo müsstest du diese Reihenfolge selbst kennen und sicherstellen.

Claude Code hilft hier direkt: Wenn deine Pipeline langsam ist oder Tasks in der falschen Reihenfolge laufen, kannst du die turbo.json übergeben und fragen, warum bestimmte Pakete nicht parallel laufen. Claude Code liest die Abhängigkeitsstruktur und erklärt, welche dependsOn-Konfiguration das Problem verursacht.

4. Caching: lokal und remote

Das lokale Cache ist standardmäßig aktiv und liegt unter .turbo/cache. Für Teams ist das alleine nicht ausreichend — jeder Entwickler und jeder CI-Runner hat seinen eigenen lokalen Cache, und die Arbeit des anderen kommt nicht an.

Hier kommt Remote Caching ins Spiel. Turborepo unterstützt Vercel Remote Cache nativ, aber auch selbst gehostete Lösungen via kompatible S3-Endpunkte. Die Aktivierung für Vercel:

# Einmalig authentifizieren
npx turbo login

# Remote Cache aktivieren
npx turbo link

Danach teilen alle Entwickler und CI-Runners denselben Cache. Wenn Entwicklerin A gerade das ui-Paket gebaut hat, muss Entwickler B es nicht mehr bauen — und der CI-Runner erst recht nicht. In großen Teams reduziert das die durchschnittliche CI-Laufzeit um 40–70 %, weil viele Tasks auf Cache-Treffer laufen.

5. Workspace-Packages strukturieren

Ein typisches Turborepo-Monorepo hat zwei Verzeichnisse auf oberster Ebene: apps/ für deploybare Anwendungen und packages/ für gemeinsam genutzte Bibliotheken. Die Workspace-Konfiguration landet in package.json im Root:

{
  "name": "my-monorepo",
  "private": true,
  "workspaces": ["apps/*", "packages/*"],
  "devDependencies": {
    "turbo": "latest"
  }
}

Pakete in packages/ können dann von den Apps direkt importiert werden, als wären sie externe npm-Pakete — aber ohne Publishing. Ein packages/ui-Paket mit gemeinsamen React-Komponenten wird in einer Next.js-App einfach als import { Button } from "@repo/ui" verwendet.

"Zeig mir alle Pakete in diesem Monorepo, die von mehr als zwei Apps importiert werden und noch kein eigenes package.json haben." — dieser Claude Code Prompt findet in einem unbekannten Monorepo sofort, was in ein eigenes Paket ausgelagert werden sollte.

6. Parallelisierung richtig nutzen

Turborepo parallelisiert automatisch alle Tasks, die keine Abhängigkeiten voneinander haben. Wenn du drei unabhängige Pakete hast, laufen deren Build-Tasks gleichzeitig — begrenzt durch die Anzahl verfügbarer CPU-Kerne.

Mit --concurrency kannst du das steuern:

# Maximal 4 Tasks gleichzeitig
turbo run build --concurrency=4

# Unbegrenzt (Standard: Anzahl CPU-Kerne)
turbo run build --concurrency=100%

In CI-Umgebungen mit wenigen Kernen kann eine zu hohe Parallelisierung kontraproduktiv sein. Claude Code hilft beim Profiling: Übergib die Turborepo-Laufzeitlogs und frage, welche Pakete den kritischen Pfad bilden — also welche Tasks seriell laufen und damit die Gesamtlaufzeit bestimmen.

7. GitHub Actions Integration

Turborepo und GitHub Actions spielen gut zusammen, weil Turborepo den Cache persistent halten kann und Actions-Jobs dadurch deutlich schneller werden:

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - name: Build & Test
        run: npx turbo run build test lint
        env:
          TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
          TURBO_TEAM: ${{ vars.TURBO_TEAM }}

Die Variablen TURBO_TOKEN und TURBO_TEAM aktivieren den Remote Cache in CI. Ohne sie würde jeder CI-Run von vorne beginnen, selbst wenn sich nur eine einzige Datei geändert hat. Mit Remote Cache hingegen werden nur die tatsächlich betroffenen Pakete neu gebaut.

8. Claude Code-Tipps für Monorepo-Entwicklung

Claude Code versteht Monorepo-Strukturen besonders gut, weil es die gesamte Verzeichnisstruktur auf einmal lesen kann. Konkrete Anwendungsfälle:

• Abhängigkeitsanalyse: "Welche Pakete im packages/-Verzeichnis haben zirkuläre Abhängigkeiten?" — Claude Code liest alle package.json-Dateien und findet das Problem, das Turborepo-Builds zum Absturz bringt.
• turbo.json debuggen: Wenn ein Task unerwartet nicht gecacht wird, kann Claude Code die Cache-Inputs analysieren und zeigen, welche Datei die Invalidierung auslöst.
• Migration von Lerna: "Migriere diese Lerna-Konfiguration zu Turborepo" — Claude Code kennt beide Formate und schreibt eine äquivalente turbo.json.
• Neue Packages anlegen: Statt manuell die Boilerplate zu schreiben, kann Claude Code ein neues Paket nach dem Muster bestehender Pakete anlegen — mit korrekter tsconfig-Vererbung und Workspace-Referenzen.

Der größte Vorteil: Claude Code sieht das gesamte Monorepo in einem Kontext. Es kann Inkonsistenzen zwischen Paketen erkennen, die manuell schwer zu finden wären — etwa unterschiedliche TypeScript-Konfigurationen in Paketen, die eigentlich dieselbe Basis teilen sollten.