Wer mehrere JavaScript- oder TypeScript-Projekte gleichzeitig entwickelt und dabei gemeinsame Pakete, Design-Systeme oder Utility-Bibliotheken teilt, stößt schnell an die Grenzen klassischer Multi-Repo-Setups. Turborepo ist ein hochperformantes Build-System für JavaScript- und TypeScript-Monorepos, das von Jared Palmer entwickelt und 2021 von Vercel übernommen wurde. Es löst die wichtigsten Schmerzpunkte großer Codebasen: langsame Builds, fehlende Parallelisierung und redundante Arbeit zwischen CI-Läufen.
Was ist ein Monorepo?
Ein Monorepo ist ein einzelnes Versionskontroll-Repository, das den Code mehrerer Anwendungen und Pakete enthält. Statt separate Repos für ein Frontend, ein Backend und eine gemeinsame UI-Bibliothek zu pflegen, liegen alle drei im gleichen Git-Repository nebeneinander. Das vereinfacht die Abhängigkeitsverwaltung erheblich: Eine Änderung in der UI-Bibliothek ist sofort in beiden Anwendungen sichtbar, ohne Versionsnummern hochzuzählen und Pakete erneut zu veröffentlichen.
Eine typische Turborepo-Projektstruktur sieht wie folgt aus:
my-monorepo/
├── apps/
│ ├── web/ # Next.js-Frontend
│ └── docs/ # Dokumentationsseite
├── packages/
│ ├── ui/ # Gemeinsame React-Komponenten
│ ├── config/ # Gemeinsame ESLint- und TS-Konfigurationen
│ └── utils/ # Geteilte Hilfsfunktionen
├── turbo.json
└── package.json # Root-Workspace-DefinitionDie apps/ enthalten deploybare Anwendungen, während packages/ interne, wiederverwendbare Pakete beherbergt. Diese können per Workspace-Protokoll ("@myorg/ui": "workspace:*") als Abhängigkeiten referenziert werden.
turbo.json: Die Pipeline konfigurieren
Das Herzstück von Turborepo ist die Datei turbo.json im Wurzelverzeichnis. Hier wird definiert, welche Aufgaben (Tasks) existieren, in welcher Reihenfolge sie laufen und welche Ausgaben gecacht werden sollen:
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": [".next/**", "dist/**"]
},
"lint": {
"dependsOn": []
},
"test": {
"dependsOn": ["build"],
"outputs": ["coverage/**"]
},
"dev": {
"cache": false,
"persistent": true
}
}
}Die Notation ^build bedeutet: „Führe zuerst den build-Task aller Abhängigkeiten aus." Turborepo berechnet daraus automatisch den optimalen Ausführungsplan und parallelisiert Tasks, die voneinander unabhängig sind.
Task-Parallelisierung und Caching
Der größte Vorteil gegenüber einem simplen npm run build --workspaces ist das intelligente Caching. Turborepo erstellt einen Hash aus allen für einen Task relevanten Eingaben: Quelldateien, Abhängigkeiten, Umgebungsvariablen und die Turbo-Konfiguration selbst. Hat sich nichts geändert, wird der gecachte Ausgabe-Ordner in Millisekunden wiederhergestellt, anstatt den Build erneut auszuführen. Auf einem Entwickler-Rechner spricht man vom lokalen Cache, der im Verzeichnis node_modules/.cache/turbo abgelegt wird.
turbo build --dry=json lässt sich vorab visualisieren, welche Tasks tatsächlich ausgeführt werden und welche aus dem Cache bedient werden. Das hilft beim Debuggen von Pipeline-Konfigurationen erheblich.
Remote Caching mit Vercel
Lokales Caching hilft einzelnen Entwicklern, löst aber noch nicht das Problem redundanter CI-Läufe. Hier kommt das Remote Caching ins Spiel. Mit einem Vercel-Account lässt sich der Cache in der Cloud speichern und zwischen Teammitgliedern sowie CI/CD-Systemen teilen. Ein Build, den Kollege A bereits ausgeführt hat, muss von Kollege B oder dem CI-Server nicht mehr wiederholt werden.
Die Einrichtung ist mit zwei Befehlen erledigt:
npx turbo login
npx turbo linkAlternativ lässt sich auch ein selbst gehosteter Remote-Cache-Server nutzen, da das Protokoll offen dokumentiert ist. Projekte wie Ducktape oder das offizielle Turborepo Remote-Caching-Protokoll ermöglichen Selbst-Hosting ohne Vendor-Lock-in zu Vercel.
outputs-Verzeichnisse gelangen. Überprüft die outputs-Konfiguration in turbo.json sorgfältig, bevor ihr Remote Caching aktiviert.
Vergleich: Turborepo vs. Nx vs. Lerna vs. Changesets
| Tool | Caching | Developer Experience | Ökosystem | Remote Cache |
|---|---|---|---|---|
| Turborepo | Lokal + Remote (Vercel) | Sehr einfach, wenig Konfiguration | Agnostisch (npm, pnpm, yarn) | Vercel oder selbst gehostet |
| Nx | Lokal + Remote (Nx Cloud) | Leistungsstark, aber komplex | Angular-Fokus, viele Plugins | Nx Cloud (kommerziell) |
| Lerna | Kein eigenes Caching | Historisch, veraltet wirkend | Npm-Workspaces-basiert | Nicht vorhanden |
| Changesets | Kein Caching | Fokus auf Versionierung/Publishing | Ergänzt andere Tools | Nicht vorhanden |
Lerna, das ursprünglich populärste Monorepo-Tool, hat in den letzten Jahren an Relevanz verloren. Es wurde primär für das Veröffentlichen von npm-Paketen entwickelt und bietet kein eigenes Caching. Changesets hingegen ist kein Build-System, sondern ein Werkzeug für Versionsverwaltung und Changelog-Generierung – es ergänzt Turborepo oder Nx, ersetzt sie aber nicht. Nx ist die leistungsstärkste Alternative zu Turborepo, erfordert aber deutlich mehr Konfiguration und bringt eine stärkere Meinung über die Projektstruktur mit.
Die offizielle Dokumentation von Turborepo ist unter turbo.build/repo/docs erreichbar. Für einen schnellen Einstieg empfiehlt sich das offizielle Starter-Template: npx create-turbo@latest. Das GitHub-Repository mit Beispiel-Projekten findet sich bei github.com/vercel/turborepo.
Wann lohnt sich Turborepo?
Turborepo entfaltet seinen vollen Nutzen ab einer gewissen Projektgröße. Für ein einzelnes Projekt oder ein sehr kleines Team mit einem einzigen Deployment-Ziel ist der Setup-Aufwand möglicherweise nicht gerechtfertigt. Sobald jedoch mehr als zwei Anwendungen gemeinsame Codebasis teilen oder ein Team von mehr als drei bis fünf Personen an verwandten Projekten arbeitet, zahlt sich das Monorepo-Setup mit Turborepo schnell aus. Build-Zeiten können in großen Projekten von mehreren Minuten auf wenige Sekunden sinken, weil unveränderte Pakete schlicht nicht neu gebaut werden.
Häufig gestellte Fragen
- Kann ich Turborepo mit pnpm-Workspaces verwenden?
- Ja, Turborepo ist agnostisch gegenüber dem Paketmanager. Es funktioniert mit npm-, yarn- und pnpm-Workspaces gleichermaßen. Die Workspace-Konfiguration liegt im jeweiligen Paketmanager, Turborepo übernimmt nur den Task-Runner-Teil.
- Was passiert, wenn ich keinen Vercel-Account für Remote Caching nutzen möchte?
- Das Remote-Caching-Protokoll von Turborepo ist offen und es existieren selbst hostbare Alternativen. Außerdem ist Remote Caching vollständig optional – lokales Caching funktioniert ohne jeden Account und bringt bereits erhebliche Geschwindigkeitsgewinne.
- Wie unterscheidet sich Turborepo von einem einfachen Makefile oder Shell-Skript?
- Turborepo versteht den Abhängigkeitsgraphen zwischen Paketen und Tasks. Es kann Tasks automatisch parallelisieren, Outputs cachen und bei Änderungen nur betroffene Tasks neu ausführen. Ein Shell-Skript muss all das manuell und fehleranfällig abbilden.
- Ist Turborepo für Open-Source-Projekte kostenlos?
- Turborepo selbst ist vollständig open source und kostenlos. Kosten entstehen nur, wenn man den kommerziellen Remote-Cache-Dienst von Vercel in großem Umfang nutzt. Selbst gehostete Lösungen sind kostenlos.