Turborepo Monorepo-Leitfaden: Verwalten von Multi-App-Projekten

Monorepos, das mehrere Anwendungen und gemeinsam genutzte Pakete enthält, ist heute die Standardarchitektur für Unternehmen, die miteinander verbundene Softwareprodukte entwickeln. Turborepo, übernommen von Vercel, bietet die Build-Orchestrierungsschicht, die Monorepos praktisch macht – die Handhabung von Aufgabenabhängigkeiten, Caching und parallele Ausführung über Dutzende von Paketen hinweg.

Wichtige Erkenntnisse

– Turborepo-Remote-Caching kann die CI-Erstellungszeiten bei inkrementellen Änderungen um 80–90 % reduzieren – Task-Pipelines stellen sicher, dass Pakete automatisch in der richtigen Abhängigkeitsreihenfolge erstellt werden – Gemeinsam genutzte Pakete (Typen, Validatoren, Dienstprogramme) verhindern die Codeduplizierung zwischen Apps – pnpm-Arbeitsbereiche bieten eine festplatteneffiziente Abhängigkeitsverwaltung für Monorepos

---

Monorepo-Architektur

Verzeichnisstruktur

Ein typisches Turborepo-Monorepo trennt Anwendungen von gemeinsam genutzten Paketen:

my-monorepo/
  apps/
    api/           # NestJS backend
    web/           # Next.js frontend
    docs/          # Documentation site
    mobile/        # React Native app
  packages/
    db/            # Drizzle ORM schemas and migrations
    types/         # Shared TypeScript types
    validators/    # Zod validation schemas
    utils/         # Shared utility functions
    ui/            # Shared UI components
    config/        # Shared configuration (ESLint, TypeScript)
  turbo.json       # Turborepo configuration
  pnpm-workspace.yaml
  package.json     # Root package.json

Arbeitsbereichskonfiguration

Definieren Sie Arbeitsbereiche in pnpm-workspace.yaml:

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

Jeder Arbeitsbereich verfügt über eine eigene package.json mit Abhängigkeiten und Skripten. Auf freigegebene Pakete wird mithilfe des Workspace-Protokolls verwiesen:

{
  "dependencies": {
    "@myorg/types": "workspace:*",
    "@myorg/validators": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

---

Turborepo-Konfiguration

Aufgabenpipeline

turbo.json definiert, wie Aufgaben zueinander in Beziehung stehen:

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

Schlüsselkonzepte:

• dependsOn: ["^build"]: Das Caretzeichen (^) bedeutet „zuerst alle Abhängigkeiten erstellen“. Beim Erstellen der Web-App erstellt Turborepo zuerst Pakete/Typen, Pakete/Validatoren und Pakete/Dienstprogramme.
• Ausgaben: Dateien, die Turborepo zwischenspeichert. Wenn sich die Eingaben bei nachfolgenden Durchläufen nicht geändert haben, spielt Turborepo die zwischengespeicherte Ausgabe erneut ab, anstatt sie neu zu erstellen.
• persistent: true: Für Entwicklungsserver, die weiterlaufen.
• cache: false: Deaktivieren Sie das Caching für Aufgaben, die immer ausgeführt werden müssen (z. B. Entwicklungsserver).

---

Freigegebene Pakete

Typenpaket

Zentralisieren Sie TypeScript-Typen, die in allen Apps verwendet werden:

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user" | "support";
  createdAt: Date;
}

export type CreateUserDTO = Omit<User, "id" | "createdAt">;
export type UpdateUserDTO = Partial<CreateUserDTO>;

Validatoren-Paket

Von Frontend und Backend gemeinsam genutzte Zod-Schemata:

// packages/validators/src/user.ts
import { z } from "zod";

export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(255),
  role: z.enum(["admin", "user", "support"]),
});

Build-Konfiguration

Freigegebene Pakete müssen vorab erstellt werden, bevor Apps sie nutzen können. Konfigurieren Sie jedes Paket mit einem Build-Skript, das TypeScript zu JavaScript kompiliert:

{
  "scripts": {
    "build": "tsc --project tsconfig.json",
    "dev": "tsc --watch"
  }
}

---

Caching-Strategie

Lokales Caching

Turborepo speichert Aufgabenausgaben standardmäßig in node_modules/.cache/turbo zwischen. Wenn Sie Turbo Build ausführen und sich nichts geändert hat, gibt Turborepo die zwischengespeicherte Ausgabe in Millisekunden wieder.

Remote-Caching

Aktivieren Sie für CI/CD Remote-Caching, um Build-Artefakte zwischen Teammitgliedern und CI-Ausführungen zu teilen:

npx turbo login
npx turbo link

Remote-Caching bedeutet, dass ein auf einem Entwicklercomputer oder CI-Lauf abgeschlossener Build für alle verfügbar ist. Die Auswirkungen sind dramatisch: Inkrementelle CI-Builds dauern von 10 Minuten auf unter 1 Minute.

---

Entwicklungsworkflow

Alle Apps ausführen

pnpm dev       # Starts all apps and watches all packages

Turborepo erstellt zuerst gemeinsam genutzte Pakete (da dev von ^build abhängt) und startet dann parallel App-Entwicklungsserver. Änderungen an freigegebenen Paketen lösen Neuerstellungen aus, die sich auf verbrauchende Apps übertragen.

Bestimmte Apps ausführen

pnpm dev --filter=web     # Only the web app and its dependencies
pnpm dev --filter=api     # Only the API and its dependencies

Das Filtern ist für große Monorepos unerlässlich, bei denen nicht alles gestartet werden muss.

---

CI/CD-Optimierung

Erkennung betroffener Pakete

Turborepo ermittelt, welche Pakete sich seit dem letzten Commit geändert haben, und führt nur Aufgaben für betroffene Pakete aus:

turbo build --filter=...[HEAD^1]

Dadurch wird der Build nur für Pakete ausgeführt, die sich im letzten Commit geändert haben, und für deren abhängige Pakete.

Parallele Ausführung

Turborepo führt unabhängige Aufgaben parallel aus. Wenn Pakete/Typen und Pakete/Dienstprogramme keine Abhängigkeitsbeziehung haben, werden sie gleichzeitig erstellt. Der Grad der Parallelität passt sich den verfügbaren CPU-Kernen an.

---

Häufig gestellte Fragen

F: Wie viele Pakete kann ein Turborepo-Monorepo verarbeiten?

Turborepo verwaltet Monorepos mit Hunderten von Paketen. Die Leistung lässt sich gut skalieren, da das Aufgabendiagramm beim Start analysiert wird und Caching bedeutet, dass die meisten Pakete Builds bei inkrementellen Änderungen überspringen.

F: Sollten wir pnpm oder npm für Arbeitsbereiche verwenden?

pnpm wird für Monorepos dringend empfohlen. Sein inhaltsadressierbarer Speicher dedupliziert Abhängigkeiten zwischen Paketen und spart so erheblich Speicherplatz und Installationszeit. pnpm-Arbeitsbereiche sind außerdem strenger bei der Abhängigkeitsauflösung und erkennen fehlende Abhängigkeitsdeklarationen.

F: Wie gehen wir mit unterschiedlichen Node.js-Versionen in verschiedenen Apps um?

Verwenden Sie das Feld „engines“ in jeder package.json, um die Versionsanforderungen von Node.j anzugeben. Bei Laufzeitunterschieden konfigurieren Sie CI so, dass pro App die entsprechende Version verwendet wird.

F: Können wir Turborepo schrittweise einführen?

Ja. Fügen Sie turbo.json zu einem vorhandenen PNPM-Arbeitsbereichsprojekt hinzu und konfigurieren Sie Aufgabenpipelines. Vorhandene Skripte funktionieren weiterhin. Sie profitieren sofort von Caching und Aufgabenkoordinierung, ohne dass eine Umstrukturierung erforderlich ist.

---

Was kommt als nächstes?

Turborepo verwandelt die Monorepo-Entwicklung von einer Wartungslast in einen Produktivitätsmultiplikator. Beginnen Sie mit einer einfachen Struktur und erweitern Sie sie entsprechend den Anforderungen Ihres Projekts.

Kontaktieren Sie ECOSIRE für Monorepo-Architekturberatung oder erkunden Sie unsere Odoo-Integrationsdienste für Multi-App-ERP-Architekturen.

---

Herausgegeben von ECOSIRE – unterstützt Unternehmen bei der Skalierung mit Unternehmenssoftwarelösungen.