Claude Code und Turborepo: Praxisguide für Monorepos

Warum Claude Code gut zu Turborepo passt

Ein Monorepo verwaltet mehrere Anwendungen und gemeinsame Packages in einem Repository. Anfangs reichen apps/web und packages/ui. Später kommen Admin-Oberflächen, Dokumentation, Utility-Pakete, mehrere Deployments und eine CI dazu, die zu langsam wird, weil sie bei jedem Pull Request alles ausführt.

Turborepo bringt Ordnung durch einen Task-Graphen und Cache. Claude Code wird wertvoll, wenn es nicht nur Konfiguration erzeugt, sondern das Repository prüft: package.json lesen, Abhängigkeiten zwischen Packages erklären, fehlende outputs finden und eine kleinere CI-Auswahl vorschlagen.

Dieser Guide basiert auf Turborepo v2 mit Stand vom 2. Juni 2026. In turbo.json wird tasks verwendet, nicht das alte pipeline. Für Anpassungen sollten die offiziellen Quellen offen sein: Turborepo configuration, turbo run, Remote Caching und Claude Code memory.

Passende interne Artikel sind Monorepo Management, pnpm workspace mit Claude Code und Claude Code CI/CD Setup.

Zielstruktur und drei praktische Fälle

Das Ziel ist ein kleines TypeScript-Monorepo auf pnpm workspace. Klein anzufangen ist Absicht: Claude Code folgt klaren Grenzen besser als unscharfen Packages wie shared oder common.

flowchart LR
  web["apps/web\nKunden-App"] --> ui["packages/ui\nGemeinsame UI"]
  admin["apps/admin\nAdmin-App"] --> ui
  web --> utils["packages/utils\nGemeinsame Funktionen"]
  admin --> utils
  ui --> tsconfig["packages/tsconfig\nTS-Konfig"]
  utils --> tsconfig

Der erste Fall ist ein Produkt mit Kunden-App und Admin-App, die Buttons, Formulare und Validierungen teilen. Die Trennung von packages/ui und packages/utils verhindert, dass Claude Code visuelle Komponenten und Geschäftslogik vermischt.

Der zweite Fall ist eine Content- oder Dokumentationsplattform. Landing Page, Dokumentation und internes Dashboard liegen oft im selben Repository. Jede PR vollständig zu bauen wird langsam. --affected und --filter prüfen nur geänderte Packages und deren Abhängige.

Der dritte Fall ist ein SaaS mit Umsatzpfaden. Pricing, Signup, Account Settings und Admin-Funktionen teilen häufig kleine Packages. Wenn lint, type-check, test und build stabil sind, kann Claude Code einen CTA ändern, während CI defekten gemeinsamen Code stoppt.

Minimale Struktur kopieren

Zuerst wird die Repository-Form festgelegt. Entscheidend ist nicht die Anzahl der Packages, sondern eine Verantwortung, die man in einem Satz beschreiben kann.

acme-monorepo/
  apps/
    web/
      package.json
      src/
    admin/
      package.json
      src/
  packages/
    ui/
      package.json
      src/
    utils/
      package.json
      src/
    tsconfig/
      package.json
      base.json
  pnpm-workspace.yaml
  package.json
  turbo.json
  CLAUDE.md

pnpm-workspace.yaml bleibt bewusst kurz.

packages:
  - "apps/*"
  - "packages/*"

Im Root-package.json stehen die Turborepo-Kommandos, die Team und Claude Code wiederverwenden. Am 2. Juni 2026 waren turbo@2.9.16 und pnpm@11.5.1 als veröffentlichte Versionen verifiziert; im echten Projekt sorgt der Lockfile für Reproduzierbarkeit.

{
  "name": "acme-monorepo",
  "private": true,
  "packageManager": "pnpm@11.5.1",
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "type-check": "turbo run type-check",
    "check": "turbo run lint type-check test build",
    "check:affected": "turbo run lint type-check test build --affected"
  },
  "devDependencies": {
    "turbo": "^2.9.16",
    "typescript": "^5.8.3"
  }
}

Interne Packages nutzen workspace:*. Damit wird das Package aus diesem Workspace aufgelöst und nicht versehentlich aus einem Registry bezogen.

{
  "name": "@acme/ui",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "lint": "eslint src --max-warnings=0",
    "type-check": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run"
  },
  "devDependencies": {
    "@acme/tsconfig": "workspace:*",
    "typescript": "^5.8.3",
    "vitest": "^3.1.0",
    "eslint": "^9.25.0"
  }
}

turbo.json mit tasks und outputs definieren

Das Root-turbo.json ist der Task-Vertrag des Repositories. Jeder Schlüssel unter tasks sucht gleichnamige Scripts in den Packages. ^build bedeutet: Zuerst werden die Abhängigkeits-Packages gebaut, dann das aktuelle Package.

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": ["pnpm-lock.yaml", "tsconfig.base.json", ".env.example"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "out/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

outputs beschreibt Artefakte, die sicher aus dem Cache wiederhergestellt werden können. Zu wenig davon macht den Cache nutzlos. Zu viel davon speichert temporäre Dateien und interne Framework-Caches. Für Next.js ist der Ausschluss von .next/cache/** meist der saubere Startpunkt.

Wenn eine App besondere Artefakte erzeugt, kann sie ein eigenes turbo.json im Package haben. Arrays ersetzen geerbte Werte standardmäßig; mit $TURBO_EXTENDS$ am Anfang wird ergänzt statt ersetzt.

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    }
  }
}

CI berechenbar machen

Turborepo zeigt seinen Nutzen besonders in CI. --affected braucht aber Git-Historie. Ein zu flacher Checkout in GitHub Actions kann dazu führen, dass alle Packages als geändert gelten. Verwenden Sie fetch-depth: 0.

name: turbo-ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 11.5.1
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run lint type-check test build --affected
      - run: pnpm turbo run build --dry=json > turbo-plan.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: turbo-plan
          path: turbo-plan.json

Für Remote Cache wird das Repository lokal mit pnpm dlx turbo login und pnpm dlx turbo link verbunden. In CI kommen TURBO_TOKEN und TURBO_TEAM aus Secrets. Logs können ebenfalls als Artefakte behandelt werden, daher sollten Build-Scripts keine API-Keys, Kundendaten oder Session Tokens ausgeben.

Diese Kommandos gehören in CLAUDE.md, damit Claude Code sie nicht jedes Mal erraten muss.

pnpm turbo run build --dry=json
pnpm turbo run build --filter=@acme/web...
pnpm turbo run test --filter=...[origin/main]
pnpm turbo run lint --filter=!./apps/docs
pnpm turbo run build --cache=local:rw,remote:r
pnpm turbo run build --force

Prompt für Claude Code

Bitten Sie nicht nur um “Turborepo einrichten”. Geben Sie Grenzen, Verbote und Prüfkommandos mit.

Dieses Repository ist ein Turborepo v2 + pnpm workspace Monorepo.

Grenzen:
- apps/* sind deploybare Anwendungen.
- packages/ui enthält nur visuelle Komponenten.
- packages/utils enthält nur framework-unabhängige Funktionen.
- packages/* darf nicht von apps/* abhängen.
- turbo.json muss tasks verwenden, nicht pipeline.

Aufgabe:
1. Lies package.json und turbo.json, dann erkläre den Task-Dependency-Graph.
2. Nenne fehlende oder verdächtige outputs für den Cache.
3. Wenn Änderungen nötig sind, mache den kleinsten sicheren Diff.
4. Führe diese Kommandos aus und berichte das Ergebnis:

pnpm turbo run lint type-check test build --affected
pnpm turbo run build --dry=json

Dieser Prompt reduziert den typischen KI-Fehler: eine große, seitliche Umstrukturierung. Er hilft auch gegen schlechte Vorschläge wie HTTP-Aufrufe in packages/ui, Next.js-Abhängigkeiten in packages/utils oder CI, die nur Vollbuilds kennt.

Typische Fehler

Der erste Fehler ist das Kopieren alter Beispiele mit pipeline. Turborepo v2 verwendet tasks. Bei einer Migration sollte Claude Code jede geänderte Option anhand der offiziellen Dokumentation erklären.

Der zweite Fehler ist zu viel Cache. node_modules/**, temporäre Logs und nicht deploybare interne Caches gehören nicht in outputs. Cachen Sie Build-Artefakte, nicht den ganzen Workspace.

Der dritte Fehler ist --affected ohne ausreichende Git-Historie. Wenn base und head im Checkout fehlen, kann Turborepo die richtigen Packages nicht berechnen.

Der vierte Fehler ist ein zu großer Auftrag an Claude Code. Führen Sie erst Turborepo ein, dann Root-Scripts, dann CI. Package-Splitting, ESLint-Migration und Dependency-Upgrades sollten getrennte Schritte sein.

Der fünfte Fehler ist übertriebene Wiederverwendung. Ein riesiges packages/shared macht kleine Änderungen global. Klar benannte Packages wie ui, utils, contracts und tsconfig sind leichter zu prüfen.

Monetarisierung und nächste Schritte

Turborepo ist nicht nur ein Speed-Tool. Es schützt Umsatzpfade. Eine Content-Seite kann Veröffentlichungen stoppen, wenn der Build bricht. Ein SaaS prüft Pricing, Signup, Account Settings und Admin in einem wiederholbaren Ablauf. Bei Beratungsteams verkürzt eine schnellere CI auch Review-Wartezeiten.

ClaudeCodeLab hilft Teams, daraus eine feste Praxis zu machen: CLAUDE.md, Package-Grenzen, CI-Kommandos, Review-Prompts und Rollout-Regeln. Zum Selbststudium passen Monorepo Management und CI/CD Setup. Für Team-Einführung starten Sie mit training / consultation.

Ergebnis aus dem Praxistest

Masa hat dieses Muster auf ein kleines Repository mit zwei Vite-Apps und einem gemeinsamen UI-Package angewendet. Der erste Lauf führte alle Tasks aus, danach gab es Cache-Hits bei build und type-check. Das erste outputs war zu breit und speicherte interne Framework-Caches, was CI-Artefakte unübersichtlich machte. Stabil wurde die Version aus diesem Artikel: v2 tasks, enge outputs, affected-Prüfung und ein Claude-Code-Prompt, der Grenzen prüft, bevor Dateien geändert werden.