Claude Code et Turborepo : guide pratique du monorepo

Pourquoi associer Claude Code et Turborepo

Un monorepo place plusieurs applications et packages partagés dans un même dépôt. Au départ, apps/web et packages/ui suffisent. Puis arrivent une application d’administration, une documentation, des utilitaires partagés, plusieurs builds et une CI qui relance tout à chaque pull request.

Turborepo aide avec un graphe de tâches et un cache. Claude Code devient utile lorsqu’il lit le dépôt comme un reviewer : il inspecte package.json, explique les dépendances entre packages, repère les outputs manquants et propose une commande CI limitée aux zones réellement touchées.

Ce guide part de Turborepo v2 au 2 juin 2026. Dans turbo.json, la clé actuelle est tasks, pas l’ancien pipeline. Pour adapter les exemples, gardez les sources officielles ouvertes : Turborepo configuration, turbo run, Remote Caching et Claude Code memory.

Pour le contexte ClaudeCodeLab, lisez aussi gestion des monorepos, pnpm workspace avec Claude Code et CI/CD avec Claude Code.

Structure cible et trois cas d’usage

La cible est un petit monorepo TypeScript sur pnpm workspace. Commencer petit est volontaire : Claude Code respecte mieux des limites explicites que des packages vagues comme shared ou common.

flowchart LR
  web["apps/web\nApp client"] --> ui["packages/ui\nUI partagée"]
  admin["apps/admin\nApp admin"] --> ui
  web --> utils["packages/utils\nFonctions partagées"]
  admin --> utils
  ui --> tsconfig["packages/tsconfig\nConfig TS"]
  utils --> tsconfig

Premier cas : une application client et une application admin partagent boutons, formulaires et validations. Séparer packages/ui de packages/utils évite que Claude Code mélange composants visuels, logique métier et appels réseau.

Deuxième cas : une plateforme de contenu avec landing page, documentation et tableau de bord interne. Tout exécuter à chaque PR devient lent. --affected et --filter permettent de vérifier les packages modifiés et ceux qui en dépendent.

Troisième cas : un SaaS orienté conversion. Pricing, inscription, paramètres de compte et administration partagent souvent des petits packages. Si lint, type-check, test et build sont stables, Claude Code peut modifier un CTA sans contourner la sécurité de CI.

Copier la structure minimale

Commencez par figer la forme du dépôt. Le but n’est pas de multiplier les packages, mais de rendre chaque responsabilité lisible.

acme-monorepo/
  apps/
    web/
      package.json
      src/
    admin/
      package.json
      src/
  packages/
    ui/
      package.json
      src/
    utils/
      package.json
      src/
    tsconfig/
      package.json
      base.json
  pnpm-workspace.yaml
  package.json
  turbo.json
  CLAUDE.md

Le fichier pnpm-workspace.yaml reste très court.

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

Dans le package.json racine, regroupez les commandes Turborepo que l’équipe et Claude Code doivent réutiliser. Le 2 juin 2026, les versions publiées vérifiées étaient turbo@2.9.16 et pnpm@11.5.1; dans un vrai projet, le lockfile garantit la reproductibilité.

{
  "name": "acme-monorepo",
  "private": true,
  "packageManager": "pnpm@11.5.1",
  "scripts": {
    "dev": "turbo dev",
    "build": "turbo run build",
    "lint": "turbo run lint",
    "test": "turbo run test",
    "type-check": "turbo run type-check",
    "check": "turbo run lint type-check test build",
    "check:affected": "turbo run lint type-check test build --affected"
  },
  "devDependencies": {
    "turbo": "^2.9.16",
    "typescript": "^5.8.3"
  }
}

Les packages internes utilisent workspace:*. Cela indique au package manager de résoudre le package dans le workspace, au lieu de récupérer par erreur un package du registry.

{
  "name": "@acme/ui",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "lint": "eslint src --max-warnings=0",
    "type-check": "tsc -p tsconfig.json --noEmit",
    "test": "vitest run"
  },
  "devDependencies": {
    "@acme/tsconfig": "workspace:*",
    "typescript": "^5.8.3",
    "vitest": "^3.1.0",
    "eslint": "^9.25.0"
  }
}

Définir turbo.json avec tasks et outputs

Le turbo.json racine est le contrat de tâches du dépôt. Chaque clé dans tasks correspond aux scripts du même nom dans les packages. ^build signifie que les dépendances du package doivent être construites avant le package courant.

{
  "$schema": "https://turborepo.dev/schema.json",
  "globalDependencies": ["pnpm-lock.yaml", "tsconfig.base.json", ".env.example"],
  "globalEnv": ["NODE_ENV"],
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "!.next/cache/**", "out/**"]
    },
    "lint": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"]
    },
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

outputs décrit les artefacts que Turborepo peut restaurer depuis le cache. Trop peu d’outputs rendent le cache inutile. Trop d’outputs stockent des fichiers temporaires et des caches internes. Pour Next.js, exclure .next/cache/** est souvent le réglage le plus propre.

Si une application produit des artefacts spécifiques, ajoutez un turbo.json dans ce package. Les tableaux remplacent la configuration héritée par défaut ; utilisez $TURBO_EXTENDS$ en première position pour ajouter sans perdre la configuration racine.

{
  "extends": ["//"],
  "tasks": {
    "build": {
      "outputs": ["$TURBO_EXTENDS$", ".next/**", "!.next/cache/**"],
      "env": ["NEXT_PUBLIC_API_URL"]
    }
  }
}

Rendre la CI ennuyeuse

Turborepo montre sa valeur en CI, mais --affected a besoin de l’historique Git. Dans GitHub Actions, un checkout trop superficiel peut faire croire que tous les packages ont changé. Utilisez fetch-depth: 0.

name: turbo-ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
        with:
          version: 11.5.1
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm turbo run lint type-check test build --affected
      - run: pnpm turbo run build --dry=json > turbo-plan.json
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: turbo-plan
          path: turbo-plan.json

Pour Remote Cache, liez le dépôt avec pnpm dlx turbo login puis pnpm dlx turbo link, et fournissez TURBO_TOKEN et TURBO_TEAM dans les secrets CI. Les logs peuvent aussi devenir des artefacts : évitez d’afficher clés API, données clients ou jetons de session.

Ajoutez ces commandes à CLAUDE.md pour que Claude Code les réutilise.

pnpm turbo run build --dry=json
pnpm turbo run build --filter=@acme/web...
pnpm turbo run test --filter=...[origin/main]
pnpm turbo run lint --filter=!./apps/docs
pnpm turbo run build --cache=local:rw,remote:r
pnpm turbo run build --force

Prompt pour Claude Code

Ne demandez pas seulement “configure Turborepo”. Donnez les limites, les interdits et les commandes de vérification.

Ce dépôt est un monorepo Turborepo v2 + pnpm workspace.

Limites:
- apps/* sont des applications déployables.
- packages/ui contient uniquement des composants visuels.
- packages/utils contient uniquement des fonctions indépendantes du framework.
- packages/* ne doit pas dépendre de apps/*.
- turbo.json doit utiliser tasks, pas pipeline.

Mission:
1. Lis package.json et turbo.json, puis explique le graphe de tâches.
2. Signale les outputs de cache manquants ou suspects.
3. Si une modification est nécessaire, applique le plus petit diff sûr.
4. Exécute ces commandes et rapporte le résultat:

pnpm turbo run lint type-check test build --affected
pnpm turbo run build --dry=json

Ce prompt réduit le risque de réécriture massive. Il aide aussi à refuser les mauvaises propositions : appels HTTP dans packages/ui, dépendance Next.js depuis packages/utils, ou CI qui ne sait faire que des builds complets.

Pièges fréquents

Le premier piège est de copier un ancien exemple avec pipeline. Turborepo v2 utilise tasks. Lors d’une migration, demandez à Claude Code d’expliquer chaque clé modifiée en s’appuyant sur la documentation officielle.

Le deuxième piège est de trop mettre en cache. N’ajoutez pas node_modules/**, les logs temporaires ou les caches internes non déployables dans outputs. Cachez les artefacts de build, pas tout le workspace.

Le troisième piège est d’utiliser --affected sans historique Git suffisant. Si les commits base et head ne sont pas présents, Turborepo ne peut pas calculer le bon ensemble de packages.

Le quatrième piège est de donner trop de travail à Claude Code en une seule fois. Introduisez Turborepo, puis les scripts racine, puis la CI. Gardez le découpage de packages, la migration ESLint et les upgrades de dépendances pour des étapes séparées.

Le cinquième piège est la sur-mutualisation. Un énorme packages/shared rend chaque changement global. Des packages nommés ui, utils, contracts et tsconfig sont plus faciles à relire.

Monétisation et suite

Turborepo ne fait pas seulement gagner du temps. Il protège les chemins de revenus. Un site de contenu peut bloquer une publication si le build casse. Un SaaS peut vérifier pricing, inscription, paramètres de compte et admin dans un même flux. Une équipe de conseil réduit aussi les files d’attente de review avec une CI plus courte.

ClaudeCodeLab peut aider à transformer cela en pratique d’équipe : CLAUDE.md, limites de packages, commandes CI, prompts de review et règles de déploiement. Pour apprendre seul, continuez avec gestion des monorepos et CI/CD avec Claude Code. Pour une adoption en équipe, commencez par training / consultation.

Résultat après essai

Masa a appliqué ce modèle à un petit dépôt avec deux apps Vite et un package UI partagé. Le premier run a exécuté toutes les tâches, puis les runs suivants ont montré des hits de cache sur build et type-check. Le premier réglage outputs était trop large et stockait des caches internes du framework, ce qui rendait les artefacts CI bruyants. La version stable est celle présentée ici : tasks v2, outputs étroits, vérification affected et prompt Claude Code qui relit les limites avant de modifier les fichiers.