Claude Code & Nx: Monorepos effizient verwalten und skalieren

Wer mehrere zusammenhängende Apps und Libraries in einem Repository betreibt, kommt früher oder später an den Punkt, an dem der Build länger dauert als die Kaffeepause, Abhängigkeiten unkontrolliert wachsen und niemand mehr genau weiß, was ein einzelner Commit bricht. Nx löst diese Probleme — mit strukturierten Workspaces, intelligentem Dependency-Graph und einer Task-Pipeline, die nur baut was sich auch geändert hat.

Claude Code ist dabei kein Ersatz für Nx, sondern ein Beschleuniger: Es navigiert die Konfigurationsdateien, erklärt den Dependency-Graph, schreibt Generatoren und hilft dabei, Workspace-Regeln durchzusetzen — ohne dass man stundenlang in der Nx-Dokumentation versinkt. Dieser Artikel zeigt, wie beides zusammenwächst.

1. Warum Monorepo? Nx vs. Turborepo

Die Entscheidung für ein Monorepo ist selten eine technische — sie ist eine organisatorische. Teams, die mehrere Produkte gemeinsam nutzen (Design-System, API-Client, shared Utils), profitieren von einem einzigen Repository: ein Pull Request kann Library und alle Consumer gleichzeitig anpassen, Versionierung entfällt, Refactorings sind atomar.

Zwischen Nx und Turborepo gibt es echte Unterschiede. Turborepo ist schlanker, einfacher zu verstehen und ideal für Teams, die vor allem Build-Zeiten optimieren wollen. Nx geht weiter: Es verwaltet die Workspace-Struktur mit festen Konventionen, bietet Code-Generatoren für konsistente Projekterstellung, kennt den vollständigen Dependency-Graph und kann mit Module Federation mehrere Micro-Frontends zur Laufzeit zusammenführen.

Für Projekte mit mehr als drei bis vier Apps und einem stabilen Team ist Nx die stärkere Wahl. Für kleinere Setups oder reine Build-Pipeline-Optimierung kann Turborepo ausreichen.

2. Nx Workspace initialisieren

Ein neuer Nx-Workspace entsteht mit einem einzigen Befehl:

npx create-nx-workspace@latest mein-monorepo --preset=ts

Wer direkt mit React, Next.js oder Angular starten will, wählt den entsprechenden Preset. Nach der Initialisierung fragt Claude Code automatisch nach dem Zugriff auf nx.json, workspace.json und die bestehenden project.json-Dateien — es braucht diesen Überblick, um im weiteren Verlauf sinnvolle Vorschläge zu machen.

claude "Lies nx.json und erkläre mir die aktuelle Workspace-Konfiguration.
Was sind die konfigurierten Task-Runner und welche Defaults gelten?"

Claude Code liest die Datei, erklärt die einzelnen Felder und zeigt, welche Einstellungen für das jeweilige Projekt sinnvoll angepasst werden sollten. Das ist besonders wertvoll beim Onboarding in einen bestehenden Workspace, dessen Konfiguration über Monate gewachsen ist.

3. Libraries und Apps strukturieren

Die Stärke von Nx liegt in der klaren Trennung zwischen Apps und Libraries. Apps sind deployment-fähige Einheiten (eine Next.js-App, eine NestJS-API, eine Electron-App). Libraries sind wiederverwendbare Code-Module, die nie direkt deployed werden.

Eine bewährte Struktur für mittlere Teams:

apps/
  web/          # Next.js Frontend
  api/          # NestJS Backend
  admin/        # Admin-Oberfläche

libs/
  shared/
    ui/         # Design-System-Komponenten
    utils/      # Gemeinsame Hilfsfunktionen
    types/      # Geteilte TypeScript-Typen
  web/
    feature-auth/    # Auth-Feature für das Web-Frontend
    data-access/     # API-Calls des Web-Frontends
  api/
    data-access/     # Datenbankzugriffe des Backends

Diese Struktur lässt sich mit Claude Code analysieren und weiterentwickeln. Wenn neue Features dazukommen, fragt man nicht mehr "wo gehört das hin?" — sondern gibt den Kontext an Claude Code und bekommt eine begründete Einordnung:

claude "Ich möchte eine neue Zahlungs-Feature hinzufügen, die im Web-Frontend
und in der API genutzt wird. Wie strukturiere ich das in unserem Workspace?"

4. Code-Generatoren (nx generate) mit Claude Code nutzen

Nx-Generatoren sind eines der unterschätztesten Features des Tools. Statt Libraries manuell anzulegen, Konfigurationsdateien zu kopieren und Barrel-Exports nachzupflegen, generiert nx generate alles in einem Schritt — konsistent, vollständig, nach Team-Standard.

# Neue React-Library anlegen
nx generate @nx/react:library shared-ui --directory=libs/shared/ui

# Neue Next.js-App hinzufügen
nx generate @nx/next:application web-v2 --directory=apps/web-v2

# Neue Komponente in einer Library
nx generate @nx/react:component Button --project=shared-ui

Claude Code hilft dabei auf zwei Ebenen: Es erklärt, welcher Generator für welchen Anwendungsfall passend ist, und es schreibt eigene Custom-Generatoren, die team-spezifische Konventionen abbilden.

claude "Schreib einen Nx-Generator, der eine neue Feature-Library anlegt,
automatisch einen index.ts-Barrel-Export erstellt und die Library
als 'buildable' konfiguriert."

Das Ergebnis ist ein Generator in tools/generators/, der anschließend per nx generate workspace-generator:feature-library aufgerufen werden kann. Einmal gebaut, spart er bei jedem neuen Feature mehrere Minuten manuelle Arbeit — und vor allem: es gibt keine Abweichungen vom Standard mehr.

5. Affected-Builds: nur geänderte Projekte bauen

Das wichtigste Performance-Feature von Nx ist nx affected. Es analysiert den Git-Diff zum letzten stabilen Commit und führt Tasks nur für Projekte aus, die sich geändert haben — direkt oder durch eine Library, von der sie abhängen.

# Nur betroffene Projekte testen
nx affected --target=test

# Nur betroffene Projekte bauen
nx affected --target=build

# Vergleich gegen einen anderen Branch
nx affected --target=lint --base=main --head=HEAD

In einem Monorepo mit 20 Apps und 40 Libraries bedeutet das: Ein Bugfix in einer einzelnen Library löst nicht mehr einen vollständigen Build aller 20 Apps aus. Nur die Apps, die diese Library tatsächlich importieren, werden neu gebaut und getestet.

"In unserem Workspace hat nx affected die CI-Zeit von durchschnittlich 22 Minuten auf 4 Minuten reduziert — bei einem Monorepo mit 12 Apps und 28 Libraries."

Claude Code kann den Dependency-Graph analysieren und erklären, warum ein bestimmtes Projekt als "affected" gilt:

claude "Warum ist meine web-App als affected markiert, obwohl ich nur
eine Änderung in libs/shared/utils gemacht habe?"

6. Task-Pipeline konfigurieren

Nx versteht Abhängigkeiten zwischen Tasks. Wenn build immer vor test laufen muss, und build einer Library vor dem build der abhängigen App — das konfiguriert man einmal in nx.json:

{
  "targetDefaults": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["{projectRoot}/dist"]
    },
    "test": {
      "dependsOn": ["build"]
    },
    "lint": {
      "inputs": ["default", "{workspaceRoot}/.eslintrc.json"]
    }
  }
}

Das ^-Symbol bedeutet: "baue zuerst alle Projekte, von denen ich abhänge". Nx parallelisiert Tasks wo möglich und serialisiert wo nötig — ohne manuelle Orchestrierung.

Claude Code hilft beim Aufbau und Debuggen dieser Konfiguration:

claude "Mein Build schlägt fehl weil eine Library noch nicht gebaut ist
wenn die App sie braucht. Zeig mir wie ich die Task-Pipeline
in nx.json korrekt konfiguriere."

7. Module Federation

Für Teams, die mehrere Micro-Frontends separat deployen aber gemeinsam ausliefern wollen, bietet Nx eine erstklassige Module-Federation-Integration. Apps können zur Laufzeit Code aus anderen Apps laden — ohne gemeinsames Deployment.

# Host-App mit Module Federation
nx generate @nx/react:host shell --remotes=cart,checkout

# Remote-App
nx generate @nx/react:remote cart --host=shell

Die Konfiguration verteilt sich auf webpack.config.js (oder vite.config.ts) in jeder beteiligten App. Claude Code kann diese Konfigurationen lesen, erklären und bei Problemen — zum Beispiel Versionskonflikten bei gemeinsam genutzten Paketen — gezielt helfen:

claude "Meine Module-Federation-Remote-App schlägt mit einem
Shared-Module-Versionsfehler fehl. Lies webpack.config.js
in apps/cart und apps/shell und zeige mir die Lösung."

8. Remote Caching mit Nx Cloud

Nx speichert Task-Ergebnisse lokal im Cache. Nx Cloud erweitert das auf ein gemeinsames Team-Cache: Wenn Kollege A einen Build abgeschlossen hat, muss Kollege B auf demselben Commit denselben Build nicht nochmal ausführen — er lädt das Ergebnis aus dem Cache.

# Nx Cloud einrichten
npx nx connect-to-nx-cloud

Credentials werden als Umgebungsvariable übergeben, niemals im Code:

NX_CLOUD_ACCESS_TOKEN=process.env.NX_CLOUD_ACCESS_TOKEN

In der CI-Konfiguration wird der Token als Secret hinterlegt und per Umgebungsvariable an den Build übergeben. Claude Code kann dabei helfen, die CI-Integration aufzusetzen — GitHub Actions, GitLab CI oder CircleCI:

claude "Erstelle eine GitHub Actions Workflow-Datei, die nx affected
für Test und Build nutzt und Nx Cloud Remote Caching aktiviert.
Der Access Token kommt aus dem GitHub Secret NX_CLOUD_ACCESS_TOKEN."

9. Custom Executors und Generators schreiben

Wenn die eingebauten Nx-Executors nicht ausreichen — weil ein Build-Prozess ungewöhnlich ist, eine Deployment-Pipeline besondere Schritte braucht oder ein internes Tool integriert werden soll — schreibt man eigene Executors.

Ein Custom Executor ist eine TypeScript-Funktion, die Nx-interne APIs nutzt:

// tools/executors/deploy/executor.ts
import { ExecutorContext } from '@nx/devkit';

export interface DeployExecutorSchema {
  environment: string;
  dryRun: boolean;
}

export default async function runExecutor(
  options: DeployExecutorSchema,
  context: ExecutorContext
) {
  const projectName = context.projectName;
  const environment = options.environment;

  // Deployment-Logik hier
  // Credentials IMMER aus process.env, nie hardcoden:
  const token = process.env.DEPLOY_TOKEN;

  console.log(`Deploying ${projectName} to ${environment}...`);
  // ...

  return { success: true };
}

Claude Code kann solche Executors von Grund auf schreiben, wenn man den Zweck beschreibt:

claude "Schreib einen Nx-Executor, der eine Next.js-App nach Vercel deployed.
Der Vercel-Token kommt aus process.env.VERCEL_TOKEN, das Projekt-Handle
aus der project.json. Unterstütze --dryRun als Option."

Das Ergebnis ist sofort verwendbar — vollständig typisiert, mit korrekter executors.json-Konfiguration und einem Beispielaufruf in der Dokumentation.

Verwandte Artikel, die auf diesem Thema aufbauen:

• Claude Code & Turborepo — wenn du Turborepo statt Nx bevorzugst
• Claude Code & pnpm Workspaces — Paketmanager-Ebene im Monorepo