Claude Code et Nx Workspace : guide monorepo pratique

Nx Workspace n’est pas seulement un gros dépôt

Demander à Claude Code de “créer un monorepo” produit vite beaucoup de fichiers. Le vrai problème arrive ensuite : une modification dans apps/web casse-t-elle apps/admin ? Un bouton doit-il rester dans l’application ou partir dans une bibliothèque UI ? Faut-il lancer tous les tests à chaque pull request ?

Nx Workspace répond avec un project graph, un task graph, des commandes affected et du cache. Le modèle mental Nx explique comment Nx analyse les projets et lance uniquement le travail nécessaire. Pour débuter, voyez Nx comme une carte des dépendances et un exécuteur de tâches.

Dans ce guide, Claude Code sert de relecteur et de binôme, pas de générateur sans garde-fou. Les références officielles sont create-nx-workspace, workspace generators, affected, CI setup et caching tasks. Pour le contexte, lisez aussi gestion de monorepo avec Claude Code, pnpm workspace et configuration CI/CD.

---

Trois cas où Nx vaut le coût

Nx n’est pas nécessaire pour tous les projets. Une landing page et une petite API peuvent rester dans un dépôt simple. Nx devient utile quand les limites et le coût de vérification deviennent un vrai sujet.

Premier cas : plusieurs applications partagent des types ou de l’UI. apps/web, apps/admin, apps/api, libs/contracts et libs/ui peuvent vivre ensemble pour modifier les types d’API et les composants de base dans une même PR.

Deuxième cas : CI sélective. Si le site de contenu, les pages de formation, l’admin et l’API partagent un dépôt, tout construire à chaque PR devient lent. nx affected -t test build choisit les projets impactés à partir du diff Git et du graphe.

Troisième cas : rendre Claude Code plus sûr. Quand libs/ui ne contient que de l’UI, libs/contracts des types d’API, libs/config de la configuration, et apps/* des applications déployables, Claude Code propose des changements plus petits. C’est essentiel pour les pages monétisées, les formulaires de contact, les CTAs et le tracking.

Si vos limites ne sont pas encore claires, commencez par repo map first pass. Nx accélère une structure que l’on peut expliquer ; il ne transforme pas automatiquement un dépôt confus en architecture saine.

---

Structure cible

Le tutoriel reste volontairement petit : deux apps React, une API Node, une bibliothèque UI, une bibliothèque de contrats et une bibliothèque de configuration.

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

La règle est simple. apps/* correspond aux unités exécutées ou déployées. libs/* correspond aux briques réutilisables. Une bibliothèque ne doit pas importer depuis une application. Une bibliothèque UI ne lit pas les variables d’environnement de l’API, et une bibliothèque de contrats ne contient pas de composants React.

Donnez ce cadre à Claude Code avant les modifications :

Comprends d'abord ce Nx Workspace. Ne modifie rien tout de suite.

Règles:
- apps/web et apps/admin sont des apps frontend
- apps/api est l'API
- libs/ui contient seulement des composants UI réutilisables
- libs/contracts contient les types d'API et les Zod schemas
- libs/config contient la config ESLint, Vitest et TypeScript partagée
- libs/* ne doit pas importer apps/*

Avant les changements, inspecte nx graph. Après les changements, donne les commandes nx affected pour vérifier.

---

Installation reproductible

Les commandes supposent Node.js 20+, Git et pnpm. Les options sont explicites pour éviter les différences liées aux prompts interactifs.

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

Générez les applications et bibliothèques avec les generators Nx. Ils mettent à jour la configuration Nx, les chemins TypeScript et les métadonnées de projet de façon cohérente.

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

Inspectez avant de coder :

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

Si le graphe est déjà compliqué, simplifiez avant d’ajouter d’autres bibliothèques.

---

Lire project.json avant de le modifier

Pour débuter, project.json est la liste des tâches disponibles pour un projet.

{
  "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"]
}

Demandez d’abord une explication :

Lis apps/web/project.json et explique build, test et serve pour un débutant.
Si une modification est nécessaire, propose seulement le plus petit diff.
Ne casse pas outputs, le comportement de cache ni les relations dependsOn.

outputs compte beaucoup, car Nx l’utilise pour le cache. Un mauvais chemin peut rendre le cache inutile ou réutiliser des artefacts obsolètes.

---

Ajouter affected à la CI

affected compare les changements Git au graphe de projets et lance les tâches seulement là où il peut y avoir un impact.

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

Dans GitHub Actions, récupérez l’historique complet pour permettre la comparaison de branches. Exécutez les tâches via nx; appeler directement vitest, eslint ou tsc contourne le cache et la logique affected.

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

Pour une équipe, le cache distant Nx Cloud peut aider. Je préfère d’abord prouver le gain avec le cache local et affected, puis ajouter le cache distant quand la durée de CI devient un vrai blocage.

---

Pièges fréquents

Premier piège : créer libs/shared et tout y mettre. Avant de déplacer du code, demandez à Claude Code s’il s’agit d’UI, de contracts, de config ou d’un utilitaire pur.

Deuxième piège : importer apps/* depuis libs/*. Cela inverse la dépendance et détruit la réutilisabilité.

Troisième piège : lancer les outils bruts en CI. Préférez pnpm nx run-many -t test ou pnpm nx affected -t test.

Quatrième piège : surconcevoir la première semaine. N’ajoutez pas libs/auth, libs/domain et libs/data-access avant d’avoir une duplication réelle.

Cinquième piège : laisser Claude Code modifier sans contexte de graphe. Ajoutez pnpm nx graph avant et pnpm nx affected -t test build après.

---

Monétisation : protéger les pages qui rapportent

Sur un site comme ClaudeCodeLab, articles, pages de formation, admin, formulaires et analytics peuvent partager un dépôt. Nx ne sert pas seulement à aller vite : il aide à savoir si une page génératrice de revenus est touchée. Si libs/cta change, le graphe montre les pages à vérifier. Si libs/analytics change, affected CI indique les apps à tester.

C’est utile pour AdSense, l’affiliation, les CTAs de paiement et les formulaires de consultation. Pour standardiser Claude Code et les monorepos en équipe, consultez ClaudeCodeLab training. En solo, créez ce workspace et gardez une capture de nx graph avant d’ajouter d’autres packages.

Vérification pratique

Lors de mon test comme Masa, j’ai d’abord créé seulement web, admin, api, ui et contracts. Après un changement de type dans libs/contracts, pnpm nx affected -t test build --base=main --head=HEAD a sélectionné les apps dépendantes. Après un changement limité à libs/ui, le build API est resté hors périmètre. La leçon n’est pas de mémoriser Nx, mais de rendre le graphe visible avant de demander des modifications à Claude Code.

Résumé

Nx Workspace ne sert pas à rendre un dépôt énorme. Il rend les dépendances visibles, vérifie seulement les projets affectés et donne à Claude Code des limites claires.

Commencez petit, lisez project.json, inspectez nx graph et placez nx affected dans la CI. Claude Code devient alors un vrai relecteur de structure monorepo.