Claude Code und Nx Workspace: Monorepo-Leitfaden

Nx Workspace ist kein großes Repository, sondern eine Karte der Grenzen

Wenn du Claude Code nur bittest, “ein Monorepo zu erstellen”, entstehen schnell viele Dateien. Die schwierigeren Fragen kommen später: Bricht eine Änderung in apps/web auch apps/admin? Gehört ein Button in die App oder in eine gemeinsame UI-Library? Muss CI bei jedem Pull Request wirklich alle Tests ausführen?

Nx Workspace beantwortet diese Fragen mit Project Graph, Task Graph, affected Commands und Cache. Das offizielle Nx mental model erklärt, wie Nx Projekte analysiert und nur die nötige Arbeit ausführt. Für Einsteiger reicht diese Vorstellung: Nx ist eine Abhängigkeitskarte plus ein Task Runner.

In diesem Leitfaden ist Claude Code ein Reviewer und Pair-Programming-Werkzeug, kein Generator ohne Grenzen. Nutze die offiziellen Dokumente als Basis: create-nx-workspace, workspace generators, affected, CI setup und caching tasks. Ergänzend passen Claude Code Monorepo Management, pnpm workspace und CI/CD Setup.

Drei Fälle, in denen Nx sinnvoll ist

Nx ist stark, aber nicht für jedes kleine Projekt nötig. Eine Landingpage und eine kleine API sind in einem einfachen Repository oft schneller. Nx lohnt sich, wenn Grenzen und Prüfkosten spürbar werden.

Der erste echte Use Case sind mehrere Apps, die Typen oder UI teilen. apps/web, apps/admin, apps/api, libs/contracts und libs/ui können zusammenleben, damit API-Typen und UI-Bausteine in einem Pull Request geändert werden.

Der zweite Use Case ist selektive CI. Wenn Content-Site, Trainingsseiten, Admin und API in einem Repository liegen, wird ein kompletter Build pro PR langsam. nx affected -t test build nutzt Git-Änderungen und den Dependency Graph, um nur betroffene Projekte auszuwählen.

Der dritte Use Case ist sichereres Arbeiten mit Claude Code. Wenn libs/ui nur UI enthält, libs/contracts API-Typen, libs/config gemeinsame Tool-Konfiguration und apps/* deploybare Apps sind, werden Vorschläge kleiner. Das schützt Seiten mit AdSense, Affiliate-Blöcken, Beratungsformularen oder Checkout-CTAs.

Wenn du deine Grenzen noch nicht erklären kannst, beginne mit repo map first pass. Nx beschleunigt eine klare Struktur, repariert aber keine unklare Architektur von selbst.

Zielstruktur

Wir starten klein: zwei React-Apps, eine Node-API, eine UI-Library, eine Contracts-Library und eine Config-Library.

flowchart LR
  web["apps/web\nReact + Vite"] --> ui["libs/ui\nUI primitives"]
  admin["apps/admin\nReact + Vite"] --> ui
  web --> contracts["libs/contracts\nAPI types"]
  admin --> contracts
  api["apps/api\nNode API"] --> contracts
  web --> config["libs/config\nlint/test config"]
  api --> config

Die Regel ist einfach: apps/* sind Einheiten, die gestartet oder deployed werden. libs/* sind wiederverwendbare Bausteine. Eine Library darf nicht aus einer App importieren. Eine UI-Library liest keine API-Umgebungsvariablen, und eine Contracts-Library enthält keine React-Komponenten.

Gib Claude Code zuerst die Grenzen:

Verstehe zuerst diesen Nx Workspace. Bearbeite noch keine Dateien.

Regeln:
- apps/web und apps/admin sind Frontend-Apps
- apps/api ist die API
- libs/ui enthält nur wiederverwendbare UI-Komponenten
- libs/contracts enthält API-Typen und Zod-Schemas
- libs/config enthält gemeinsame ESLint-, Vitest- und TypeScript-Konfiguration
- libs/* darf nicht aus apps/* importieren

Prüfe vor Änderungen nx graph. Gib nach Änderungen die nötigen nx affected Befehle zur Verifikation aus.

Reproduzierbares Setup

Die Befehle setzen Node.js 20+, Git und pnpm voraus. Die Optionen sind explizit, damit das Tutorial ohne interaktive Abweichungen wiederholbar bleibt.

npx create-nx-workspace@latest acme-nx \
  --workspaceType=integrated \
  --preset=apps \
  --packageManager=pnpm \
  --nxCloud=skip \
  --interactive=false

cd acme-nx
pnpm nx add @nx/react
pnpm nx add @nx/node

Erzeuge Apps und Libraries mit Nx Generators. Sie aktualisieren Nx-Konfiguration, TypeScript-Pfade und Projektmetadaten konsistent.

pnpm nx g @nx/react:app web \
  --directory=apps/web \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=playwright \
  --style=css

pnpm nx g @nx/react:app admin \
  --directory=apps/admin \
  --bundler=vite \
  --unitTestRunner=vitest \
  --e2eTestRunner=none \
  --style=css

pnpm nx g @nx/node:app api \
  --directory=apps/api \
  --unitTestRunner=vitest

pnpm nx g @nx/react:lib ui \
  --directory=libs/ui \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib contracts \
  --directory=libs/contracts \
  --unitTestRunner=vitest

pnpm nx g @nx/js:lib config \
  --directory=libs/config \
  --unitTestRunner=none

Sieh dir das Ergebnis an, bevor du Code änderst:

pnpm nx graph
pnpm nx show projects
pnpm nx show project web

Wenn der Graph schon am Anfang verworren wirkt, vereinfache die Struktur, bevor du weitere Libraries anlegst.

project.json zuerst lesen

Für Einsteiger ist project.json die Liste der Jobs, die ein Projekt ausführen kann.

{
  "name": "web",
  "sourceRoot": "apps/web/src",
  "projectType": "application",
  "targets": {
    "build": {
      "executor": "@nx/vite:build",
      "outputs": ["{options.outputPath}"],
      "options": {
        "outputPath": "dist/apps/web"
      }
    },
    "test": {
      "executor": "@nx/vite:test",
      "outputs": ["{workspaceRoot}/coverage/apps/web"],
      "options": {
        "passWithNoTests": true
      }
    },
    "serve": {
      "executor": "@nx/vite:dev-server",
      "options": {
        "buildTarget": "web:build"
      }
    }
  },
  "tags": ["scope:app", "type:web"]
}

Lass Claude Code erst erklären:

Lies apps/web/project.json und erkläre build, test und serve für Einsteiger.
Wenn eine Änderung nötig ist, schlage nur den kleinsten Diff vor.
Beschädige outputs, Cache-Verhalten und dependsOn-Beziehungen nicht.

outputs ist wichtig, weil Nx es für den Cache nutzt. Ein falscher Pfad kann den Cache nutzlos machen oder veraltete Artefakte wiederverwenden.

affected in CI einsetzen

affected vergleicht Git-Änderungen mit dem Project Graph und führt Tasks nur dort aus, wo Auswirkungen möglich sind.

pnpm nx affected -t lint test build --base=main --head=HEAD
pnpm nx affected:graph --base=main --head=HEAD

In GitHub Actions brauchst du vollständige Historie für Branch-Vergleiche. Führe Tasks über nx aus; direkte Aufrufe von vitest, eslint oder tsc umgehen affected und Cache.

name: nx-ci

on:
  pull_request:
  push:
    branches: [main]

jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm nx affected -t lint test build --base=origin/main --head=HEAD --parallel=3

Für Teams kann Nx Cloud Remote Cache sinnvoll sein. Zeige zuerst den Nutzen mit lokalem Cache und affected Commands, bevor du Remote Cache einführst.

Häufige Fehler

Der erste Fehler ist libs/shared als Sammelbecken. Claude Code sollte vor dem Verschieben erklären, ob Code UI, contracts, config oder ein reines Utility ist.

Der zweite Fehler ist Import aus apps/* innerhalb von libs/*. Das dreht die Abhängigkeit um und macht Wiederverwendung schwer.

Der dritte Fehler ist direkte Tool-Ausführung in CI. Nutze lieber pnpm nx run-many -t test oder pnpm nx affected -t test.

Der vierte Fehler ist Over-Engineering in Woche eins. Lege nicht ohne echte Duplikation libs/auth, libs/domain und libs/data-access an.

Der fünfte Fehler ist Claude Code ohne Graph-Kontext. Nimm pnpm nx graph vor der Arbeit und pnpm nx affected -t test build nach der Arbeit in den Prompt auf.

Monetarisierung: Seiten schützen, die Umsatz bringen

Bei einer Seite wie ClaudeCodeLab können Artikel, Trainingsseiten, Admin, Lead-Formulare und Analytics in einem Repository liegen. Nx hilft nicht nur bei Geschwindigkeit, sondern auch bei Umsatzsicherheit. Wenn libs/cta geändert wird, zeigt der Graph, welche Seiten geprüft werden müssen. Wenn libs/analytics geändert wird, zeigt affected CI, welche Apps Smoke Tests brauchen.

Das ist wichtig für AdSense-Layouts, Affiliate-Blöcke, Checkout-CTAs und Beratungsformulare. Teams, die Claude Code und Monorepos standardisieren wollen, finden unter ClaudeCodeLab training den nächsten Schritt. Allein startest du am besten mit diesem Beispiel und speicherst einen Screenshot von nx graph.

Praktische Verifikation

In meinem Test als Masa habe ich zuerst nur web, admin, api, ui und contracts erstellt. Nach einer Typänderung in libs/contracts wählte pnpm nx affected -t test build --base=main --head=HEAD nur die abhängigen Apps aus. Bei einer Änderung nur in libs/ui blieb der API-Build außen vor. Die wichtigste Erkenntnis: Nicht Nx-Optionen auswendig lernen, sondern Graph und Grenzen sichtbar machen, bevor Claude Code editiert.

Fazit

Nx Workspace macht ein Repository nicht absichtlich groß. Es macht Abhängigkeiten sichtbar, prüft nur betroffene Projekte und gibt Claude Code klare Grenzen.

Starte klein, lies project.json, prüfe nx graph und setze nx affected in CI ein. Dann wird Claude Code vom Dateigenerator zum hilfreichen Reviewer für Monorepo-Struktur.