Guide Turborepo Monorepo : Gestion de projets multi-applications

Les monorepos contenant plusieurs applications et packages partagés constituent désormais l'architecture standard pour les entreprises qui créent des produits logiciels interconnectés. Turborepo, acquis par Vercel, fournit la couche d'orchestration de construction qui rend les monorepos pratiques : gestion des dépendances de tâches, mise en cache et exécution parallèle sur des dizaines de packages.

Points clés à retenir

• La mise en cache à distance Turborepo peut réduire les temps de création de CI de 80 à 90 % sur les modifications incrémentielles
• Les pipelines de tâches garantissent que les packages sont automatiquement construits dans le bon ordre de dépendances
• Les packages partagés (types, validateurs, utilitaires) éliminent la duplication de code entre les applications
• Les espaces de travail pnpm fournissent une gestion efficace des dépendances sur le disque pour les monorepos

---

Architecture Monorepo

Structure du répertoire

Un monorepo Turborepo typique sépare les applications des packages partagés :

my-monorepo/
  apps/
    api/           # NestJS backend
    web/           # Next.js frontend
    docs/          # Documentation site
    mobile/        # React Native app
  packages/
    db/            # Drizzle ORM schemas and migrations
    types/         # Shared TypeScript types
    validators/    # Zod validation schemas
    utils/         # Shared utility functions
    ui/            # Shared UI components
    config/        # Shared configuration (ESLint, TypeScript)
  turbo.json       # Turborepo configuration
  pnpm-workspace.yaml
  package.json     # Root package.json

Configuration de l'espace de travail

Définissez les espaces de travail dans pnpm-workspace.yaml :

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

Chaque espace de travail possède son propre package.json avec des dépendances et des scripts. Les packages partagés sont référencés à l'aide du protocole d'espace de travail :

{
  "dependencies": {
    "@myorg/types": "workspace:*",
    "@myorg/validators": "workspace:*",
    "@myorg/utils": "workspace:*"
  }
}

---

Configuration du Turborepo

Pipeline de tâches

turbo.json définit la façon dont les tâches sont liées les unes aux autres :

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"]
    },
    "dev": {
      "dependsOn": ["^build"],
      "cache": false,
      "persistent": true
    },
    "lint": {
      "dependsOn": ["^build"]
    },
    "test": {
      "dependsOn": ["build"]
    }
  }
}

Concepts clés :

• dependsOn : ["^build"] : Le caret (^) signifie "construire d'abord toutes les dépendances". Lors de la création de l'application Web, Turborepo crée d'abord les packages/types, les packages/validateurs et les packages/utils.
• sorties : fichiers mis en cache par Turborepo. Lors des exécutions suivantes, si les entrées n'ont pas changé, Turborepo relit la sortie mise en cache au lieu de la reconstruire.
• persistent : true : Pour les serveurs de développement qui continuent de fonctionner.
• cache : false : Désactivez la mise en cache pour les tâches qui doivent toujours s'exécuter (comme les serveurs de développement).

---

Forfaits partagés

Types de paquets

Centralisez les types TypeScript utilisés dans les applications :

// packages/types/src/user.ts
export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "user" | "support";
  createdAt: Date;
}

export type CreateUserDTO = Omit<User, "id" | "createdAt">;
export type UpdateUserDTO = Partial<CreateUserDTO>;

Package de validateurs

Schémas Zod partagés entre le frontend et le backend :

// packages/validators/src/user.ts
import { z } from "zod";

export const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2).max(255),
  role: z.enum(["admin", "user", "support"]),
});

Construire la configuration

Les packages partagés doivent être pré-construits avant que les applications puissent les utiliser. Configurez chaque package avec un script de build qui compile TypeScript en JavaScript :

{
  "scripts": {
    "build": "tsc --project tsconfig.json",
    "dev": "tsc --watch"
  }
}

---

Stratégie de mise en cache

Mise en cache locale

Turborepo met en cache les sorties de tâches dans node_modules/.cache/turbo par défaut. Lorsque vous exécutez Turbo build et que rien n'a changé, Turborepo relit la sortie mise en cache en millisecondes.

Mise en cache à distance

Pour CI/CD, activez la mise en cache à distance pour partager les artefacts de build entre les membres de l'équipe et les exécutions CI :

npx turbo login
npx turbo link

La mise en cache à distance signifie qu'une build terminée sur un ordinateur de développeur ou une exécution de CI est accessible à tous. L'impact est spectaculaire : la création incrémentielle de CI passe de 10 minutes à moins d'une minute.

---

Flux de travail de développement

Exécuter toutes les applications

pnpm dev       # Starts all apps and watches all packages

Turborepo crée d'abord les packages partagés (car le développement dépend de ^build), puis démarre les serveurs de développement d'applications en parallèle. Les modifications apportées aux packages partagés déclenchent des reconstructions qui se propagent aux applications consommatrices.

Exécution d'applications spécifiques

pnpm dev --filter=web     # Only the web app and its dependencies
pnpm dev --filter=api     # Only the API and its dependencies

Le filtrage est essentiel pour les grands monorepos où tout démarrer est inutile.

---

Optimisation CI/CD

Détection des packages concernés

Turborepo détermine quels packages ont été modifiés depuis la dernière validation et exécute uniquement les tâches pour les packages concernés :

turbo build --filter=...[HEAD^1]

Cela s'exécute uniquement pour les packages modifiés dans le dernier commit et leurs dépendants.

Exécution parallèle

Turborepo exécute des tâches indépendantes en parallèle. Si les packages/types et les packages/utils n'ont aucune relation de dépendance, ils sont construits simultanément. Le niveau de concurrence s'adapte aux cœurs de processeur disponibles.

---

Questions fréquemment posées

Q : Combien de packages un monorepo Turborepo peut-il gérer ?

Turborepo gère les monorepos avec des centaines de packages. Les performances évoluent bien car le graphique des tâches est analysé au démarrage et la mise en cache signifie que la plupart des packages ignorent les builds sur les modifications incrémentielles.

Q : Devons-nous utiliser pnpm ou npm pour les espaces de travail ?

pnpm est fortement recommandé pour les monorepos. Son magasin adressable par le contenu déduplique les dépendances entre les packages, économisant ainsi un espace disque et un temps d'installation considérables. Les espaces de travail pnpm sont également plus stricts en matière de résolution des dépendances, en interceptant les déclarations de dépendance manquantes.

Q : Comment gérons-nous les différentes versions de Node.js dans les applications ?

Utilisez le champ moteurs dans chaque package.json pour spécifier les exigences de version de Node.js. Pour les différences d'exécution, configurez CI pour utiliser la version appropriée par application.

Q : Pouvons-nous adopter progressivement Turborepo ?

Oui. Ajoutez turbo.json à un projet d'espace de travail pnpm existant et configurez les pipelines de tâches. Les scripts existants continuent de fonctionner. Vous bénéficiez immédiatement de la mise en cache et de l’orchestration des tâches, sans restructuration.

---

Quelle est la prochaine étape

Turborepo transforme le développement monorepo d'un fardeau de maintenance en un multiplicateur de productivité. Commencez avec une structure simple et évoluez en fonction des exigences de votre projet.

Contactez ECOSIRE pour des conseils en architecture monorepo, ou explorez nos Services d'intégration Odoo pour les architectures ERP multi-applications.

---

Publié par ECOSIRE – aider les entreprises à évoluer grâce à des solutions logicielles d'entreprise.