Architektur & Build 5. Mai 2026 11 min Lesezeit

Turborepo mit Claude Code: Monorepo-Architektur für Fullstack-Apps 2026

Turborepo ist der schnellste Weg zu einer skalierbaren Monorepo-Architektur — intelligentes Caching, parallele Builds, Shared Packages. Claude Code kennt alle Turborepo-Patterns: von der initialen Workspace-Struktur bis zu Remote Caching in CI/CD.

Wer mehrere Apps und Bibliotheken in einem Repository verwaltet, kämpft schnell mit langsamen Builds, doppeltem Code und inkonsistenten Konfigurationen. Turborepo löst genau diese Probleme — mit intelligentem Task-Caching, parallelen Pipelines und einer klaren Paketstruktur. Claude Code kennt sämtliche Turborepo-Patterns und richtet ein produktionsreifes Monorepo in Minuten ein.

Warum Turborepo 2026 der Standard ist

Monorepos sind längst kein Nischen-Pattern mehr. Große Teams bei Vercel, Microsoft und Google nutzen sie, um Konsistenz über Dutzende von Paketen zu gewährleisten. Turborepo bringt dafür drei entscheidende Vorteile:

Caching Intelligentes Task-Caching

Turborepo speichert Outputs jedes Tasks — Build-Artefakte, Test-Ergebnisse, Lint-Reports — lokal und remote. Ändert sich nichts am Input, wird der gecachte Output sofort wiederverwendet. Build-Zeit von 8 Minuten auf unter 30 Sekunden ist keine Seltenheit.

Packages Shared Packages ohne Overhead

UI-Komponenten, TypeScript-Konfigurationen, ESLint-Regeln, Utility-Funktionen — alles einmal definieren, überall verwenden. Keine Copy-Paste-Fehler, keine Versions-Drift zwischen Apps.

Pipeline Parallele Task-Ausführung

Turborepo kennt die Abhängigkeiten zwischen Paketen und führt Tasks maximal parallel aus. Tests in App A laufen gleichzeitig mit dem Build von Paket B — solange keine Abhängigkeit besteht.

Workspace-Struktur mit Claude Code aufsetzen

Der einfachste Einstieg: Claude Code direkt den initialen Setup beschreiben lassen.

Claude Code Prompt: "Erstelle ein Turborepo-Monorepo mit pnpm Workspaces. Apps: web (Next.js 15), docs (Next.js). Packages: ui (React-Komponenten), config-typescript, config-eslint. Inklusive turbo.json mit build/test/lint Pipeline."

Claude Code generiert die komplette Verzeichnisstruktur:

# Monorepo-Struktur (von Claude Code generiert)
my-monorepo/
├── apps/
│   ├── web/                    # Next.js Hauptanwendung
│   │   ├── app/
│   │   ├── package.json
│   │   └── next.config.ts
│   └── docs/                   # Dokumentations-App
│       ├── app/
│       └── package.json
├── packages/
│   ├── ui/                     # Shared UI-Bibliothek
│   │   ├── src/
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json
│   ├── config-typescript/      # Shared TS-Konfiguration
│   │   ├── base.json
│   │   ├── nextjs.json
│   │   └── package.json
│   └── config-eslint/          # Shared ESLint-Regeln
│       ├── base.js
│       ├── next.js
│       └── package.json
├── turbo.json                  # Pipeline-Konfiguration
├── package.json                # Root package.json
└── pnpm-workspace.yaml         # pnpm Workspace-Definition

pnpm Workspaces konfigurieren

Die Basis jedes pnpm-basierten Monorepos ist die pnpm-workspace.yaml:

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

Die Root-package.json definiert globale Scripts und Dev-Dependencies:

{
  "name": "my-monorepo",
  "private": true,
  "scripts": {
    "build": "turbo build",
    "dev": "turbo dev",
    "lint": "turbo lint",
    "test": "turbo test",
    "format": "prettier --write \"**/*.{ts,tsx,md}\""
  },
  "devDependencies": {
    "turbo": "^2.3.0",
    "prettier": "^3.3.0",
    "typescript": "^5.5.0"
  },
  "packageManager": "pnpm@9.0.0"
}

turbo.json: Die Pipeline-Konfiguration

Das Herzstück von Turborepo ist die Pipeline-Definition. Claude Code generiert eine optimierte Konfiguration, die Abhängigkeiten und Cache-Verhalten präzise steuert:

{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],   // erst Abhängigkeiten bauen
      "outputs": [
        ".next/**",
        "!.next/cache/**",
        "dist/**"
      ],
      "env": [
        "NODE_ENV",
        "NEXT_PUBLIC_API_URL"
      ]
    },
    "dev": {
      "cache": false,          // Dev-Server nicht cachen
      "persistent": true     // Langlebiger Prozess
    },
    "lint": {
      "outputs": [],
      "outputMode": "new-only"  // Nur neue Outputs loggen
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "inputs": [
        "src/**/*.tsx",
        "src/**/*.ts",
        "test/**/*.ts"
      ]
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    }
  }
}

Caching-Logik verstehen: Das ^-Präfix in "dependsOn": ["^build"] bedeutet: "Führe zuerst den build-Task aller Abhängigkeiten aus." Ohne ^ würde es auf Tasks im gleichen Paket verweisen. Claude Code erklärt diese Nuancen auf Nachfrage sofort.

Shared Packages: UI-Bibliothek

Der größte Vorteil eines Monorepos: geteilte UI-Komponenten. Claude Code erstellt ein vollständiges packages/ui-Paket:

// packages/ui/package.json
{
  "name": "@repo/ui",
  "version": "0.0.1",
  "private": true,
  "exports": {
    "./button": {
      "types": "./src/button.tsx",
      "default": "./src/button.tsx"
    },
    "./card": {
      "types": "./src/card.tsx",
      "default": "./src/card.tsx"
    },
    "./styles.css": "./src/styles.css"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@repo/config-typescript": "workspace:*",
    "typescript": "^5.5.0"
  }
}

// packages/ui/src/button.tsx
import * as React from "react";

interface ButtonProps {
  children: React.ReactNode;
  variant?: "primary" | "secondary" | "ghost";
  size?: "sm" | "md" | "lg";
  onClick?: () => void;
  disabled?: boolean;
  className?: string;
}

export function Button({
  children,
  variant = "primary",
  size = "md",
  onClick,
  disabled = false,
  className = "",
}: ButtonProps): JSX.Element {
  const baseClasses = "inline-flex items-center justify-center rounded-md font-medium transition-colors";
  const variantClasses = {
    primary: "bg-indigo-600 text-white hover:bg-indigo-700 disabled:bg-indigo-300",
    secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200 disabled:bg-gray-50",
    ghost: "bg-transparent hover:bg-gray-100 disabled:opacity-50",
  };
  const sizeClasses = {
    sm: "h-8 px-3 text-sm",
    md: "h-10 px-4 text-sm",
    lg: "h-12 px-6 text-base",
  };

  return (
    <button
      className={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${className}`}
      onClick={onClick}
      disabled={disabled}
    >
      {children}
    </button>
  );
}

Shared TypeScript-Konfiguration

Konsistente TypeScript-Settings über alle Pakete — Claude Code erstellt ein dediziertes Konfigurationspaket:

// packages/config-typescript/base.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Default",
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "esModuleInterop": true,
    "incremental": false,
    "isolatedModules": true,
    "lib": ["es2022", "dom", "dom.iterable"],
    "module": "NodeNext",
    "moduleDetection": "force",
    "moduleResolution": "NodeNext",
    "noUncheckedIndexedAccess": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "strict": true,
    "target": "ES2022"
  }
}

// packages/config-typescript/nextjs.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Next.js",
  "extends": "./base.json",
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "allowJs": true,
    "jsx": "preserve",
    "noEmit": true,
    "plugins": [{ "name": "next" }]
  }
}

In jeder App wird die Konfiguration dann einfach erweitert:

// apps/web/tsconfig.json
{
  "extends": "@repo/config-typescript/nextjs.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["."],
  "exclude": ["node_modules"]
}

Shared ESLint-Konfiguration

Einheitliche Linting-Regeln über alle Pakete verhindern inkonsistenten Code-Stil:

// packages/config-eslint/base.js
import js from "@eslint/js";
import eslintConfigPrettier from "eslint-config-prettier";
import turboPlugin from "eslint-plugin-turbo";
import tseslint from "typescript-eslint";
import onlyWarn from "eslint-plugin-only-warn";

/** @type {import("eslint").Linter.Config[]} */
export const config = [
  js.configs.recommended,
  eslintConfigPrettier,
  ...tseslint.configs.recommended,
  {
    plugins: {
      turbo: turboPlugin,
    },
    rules: {
      "turbo/no-undeclared-env-vars": "warn",
      "@typescript-eslint/no-unused-vars": [
        "error",
        { argsIgnorePattern: "^_" }
      ],
    },
  },
  {
    plugins: { onlyWarn },
  },
  {
    ignores: ["dist/**", ".next/**"],
  },
];

Dependency-Management mit pnpm Workspaces

Interne Pakete werden über das workspace:*-Protokoll referenziert. Das stellt sicher, dass immer die lokale Version verwendet wird — nicht eine veröffentlichte npm-Version:

// apps/web/package.json
{
  "name": "web",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@repo/ui": "workspace:*",     // lokale UI-Bibliothek
    "next": "15.2.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@repo/config-eslint": "workspace:*",
    "@repo/config-typescript": "workspace:*",
    "eslint": "^9.0.0",
    "typescript": "^5.5.0"
  },
  "scripts": {
    "build": "next build",
    "dev": "next dev --turbopack",
    "lint": "eslint . --max-warnings 0",
    "type-check": "tsc --noEmit"
  }
}

Claude Code Tipp: Mit workspace:* löst pnpm immer die lokale Paketversion auf. Bei pnpm install werden alle internen Abhängigkeiten automatisch als Symlinks im jeweiligen node_modules verknüpft. Claude Code generiert auf Nachfrage sofort die kompletten Abhängigkeitsgraphen.

Remote Caching mit Vercel

Lokales Caching ist großartig für Einzelentwickler. Im Team und in CI/CD entfaltet Remote Caching seinen vollen Wert: Ein Build auf einem Rechner wird gecacht, alle anderen Rechner und CI-Pipelines profitieren sofort.

# Remote Caching aktivieren (einmalig)
npx turbo login
npx turbo link

# Verifizieren: Remote Cache aktiv
turbo build --dry=json

Claude Code konfiguriert die Vercel Remote Cache Integration direkt in turbo.json:

{
  "$schema": "https://turbo.build/schema.json",
  "remoteCache": {
    "enabled": true,
    "signature": true  // Cache-Einträge kryptografisch signieren
  },
  "pipeline": { /* ... */ }
}

CI/CD mit GitHub Actions und Remote Caching

Ein produktionsreifer Workflow, den Claude Code in unter einer Minute erstellt:

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}

    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm

      - name: Dependencies installieren
        run: pnpm install --frozen-lockfile

      - name: Lint
        run: pnpm turbo lint

      - name: Type Check
        run: pnpm turbo type-check

      - name: Tests
        run: pnpm turbo test

      - name: Build
        run: pnpm turbo build

CI/CD Remote Cache in der Praxis

Mit gesetzten TURBO_TOKEN und TURBO_TEAM Secrets lädt Turborepo gecachte Build-Outputs direkt von Vercel herunter. Ein Paket, das sich nicht geändert hat, wird in CI in Millisekunden "gebaut" — tatsächlich nur heruntergeladen. CI-Laufzeiten sinken oft von 10+ Minuten auf unter 2 Minuten.

Claude Code: Turborepo-Upgrades und Refactoring

Das Aufsetzen ist nur der Anfang. Claude Code unterstützt aktiv bei der laufenden Weiterentwicklung des Monorepos:

Migration Bestehende Repos migrieren

Claude Code analysiert ein bestehendes Multi-Repo-Setup und erstellt einen schrittweisen Migrationsplan: welche Pakete zuerst, wie Abhängigkeiten auflösen, wie Commit-History erhalten bleibt.

Packages Neue Shared Packages extrahieren

"Extrahiere alle Datenbankzugriffe aus apps/web und apps/api in ein packages/database Paket mit Prisma" — Claude Code identifiziert Duplikate, erstellt die Paketstruktur und passt alle Imports an.

Pipeline Cache-Optimierung

Claude Code analysiert turbo build --dry=json-Outputs und erkennt, welche Tasks unnötig keine Cache-Hits produzieren — etwa weil outputs oder inputs nicht korrekt definiert sind.

Produktionsreife Monorepo-Patterns

Claude Code kennt alle etablierten Patterns für skalierbare Monorepos:

Package Boundaries: Klare API-Oberflächen über exports in package.json — kein direkter Zugriff auf interne Module
Internal Packages: Pakete mit "private": true werden nie versehentlich auf npm veröffentlicht
Task Filtering: turbo build --filter=web... baut nur die Web-App und ihre Abhängigkeiten — ideal für Partial Deployments
Affected Packages: turbo build --filter=...[HEAD^1] baut nur Pakete, die sich seit dem letzten Commit geändert haben
Changesets: Versionsverwaltung für Pakete, die veröffentlicht werden sollen — Claude Code richtet den kompletten Changeset-Workflow ein

Praxis-Tipp Affected Builds: In einem großen Monorepo mit 20+ Paketen ist das Filtern auf geänderte Pakete der wichtigste Performance-Hebel. --filter=...[origin/main] führt Tasks nur für Pakete aus, die sich gegenüber dem Main-Branch geändert haben — inklusive aller Abhängigen.

Turborepo 2.x: Was neu ist

Turborepo 2.x brachte 2025 mehrere wichtige Verbesserungen, die Claude Code vollständig kennt und nutzt:

Neues Terminal-UI: Bessere Übersicht über parallele Task-Ausführung mit interaktivem Log-Viewer
Watch-Mode: turbo watch build überwacht Dateisystem-Änderungen und führt betroffene Tasks automatisch neu aus
Verbesserte Cache-Keys: Präzisere Hashing-Algorithmen reduzieren False Positives bei Cache-Invalidierung
Task Graph Visualisierung: turbo graph erzeugt einen visuellen Abhängigkeitsgraphen aller Tasks

# Nützliche Turborepo-Befehle für den Alltag

# Welche Tasks würden laufen? (Dry-Run)
turbo build --dry

# Abhängigkeitsgraph visualisieren
turbo graph

# Nur spezifisches Paket bauen (inkl. Abhängigkeiten)
turbo build --filter=@repo/ui...

# Cache-Statistiken anzeigen
turbo build --summarize

# Cache leeren (lokaler Cache)
turbo daemon clean

# Watch-Mode für Entwicklung
turbo watch build --filter=web

Fazit: Skalierbare Architektur von Tag 1

Turborepo ist 2026 die Standard-Wahl für Monorepos — und Claude Code macht den initialen Aufwand minimal. Statt Stunden mit der Konfiguration zu verbringen, beschreibt man die gewünschte Architektur und erhält ein funktionsfähiges Setup mit korrekten tsconfig-Vererbungen, optimierten Cache-Pipelines und CI/CD-Workflows.

Der eigentliche Wert: Claude Code versteht nicht nur die Syntax, sondern die Semantik von Turborepo-Konfigurationen. Es erklärt warum dependsOn: ["^build"] korrekt ist, identifiziert Cache-Probleme in bestehenden Setups und hilft beim Skalieren von 3 auf 30 Pakete — ohne dass man selbst zum Turborepo-Experten werden muss.

Architektur-Modul im Kurs

Im Claude Code Mastery Kurs: vollständiges Monorepo-Modul mit Turborepo, pnpm Workspaces, Shared Packages, Remote Caching und CI/CD-Integration — für skalierbare Fullstack-Architekturen.

14 Tage kostenlos testen →