Gestion des dépendances

Vue d'ensemble

Le monorepo Feelbat utilise pnpm pour gérer les dépendances Node.js.

Dans un monorepo, l'ajout d'une dépendance doit toujours être fait avec attention afin d'éviter d'installer une librairie au mauvais endroit ou de créer des dépendances inutiles entre les projets.

Objectif

À la fin de ce guide, vous comprendrez :

• Comment ajouter une dépendance à un service ou une application.
• Comment ajouter une dépendance au workspace.
• Comment installer une bibliothèque locale du monorepo.
• Le rôle du fichier pnpm-workspace.yaml.
• La différence entre workspace:* et catalog:*.

Installer les dépendances

Après avoir cloné le monorepo, installez les dépendances avec :

pnpm install

Cette commande installe toutes les dépendances du workspace.

Ajouter une dépendance à un projet

Pour ajouter une dépendance à un service ou une application spécifique, utilisez --filter.

pnpm add <package-name> --filter @feelbat/<project-name>

Exemple :

pnpm add zod --filter @feelbat/auth

Cette commande ajoute zod uniquement dans le package.json du projet @feelbat/auth.

Warning

Évitez d'utiliser pnpm add <package-name> sans --filter dans le monorepo. La dépendance pourrait être ajoutée au mauvais endroit.

Ajouter une dépendance de développement

Pour ajouter une dépendance de développement à un projet spécifique :

pnpm add -D <package-name> --filter @feelbat/<project-name>

Exemple :

pnpm add -D @types/node --filter @feelbat/auth

Ajouter une dépendance au workspace

Certaines dépendances concernent tout le monorepo.

Dans ce cas, utilisez l'option -w.

pnpm add -D <package-name> -w

Exemple :

pnpm add -D prettier -w

Tip

Utilisez -w uniquement pour les dépendances réellement globales au workspace, comme les outils de formatage, de lint ou de build.

Le fichier pnpm-workspace.yaml

Le fichier pnpm-workspace.yaml décrit la configuration du workspace pnpm.

Il permet notamment de définir :

• les dossiers considérés comme des packages du workspace ;
• les dépendances synchronisées après certains scripts ;
• les versions centralisées des dépendances via les catalogs.

packages

La clé packages indique à pnpm quels dossiers font partie du workspace.

Exemple :

packages:
  - apps/**
  - libs/**

Dans cet exemple, tous les projets présents dans apps/ et libs/ sont considérés comme des packages pnpm.

Cela permet notamment à pnpm de résoudre les dépendances locales entre projets du monorepo.

syncInjectedDepsAfterScripts

La clé syncInjectedDepsAfterScripts permet de demander à pnpm de resynchroniser certaines dépendances injectées après l'exécution de scripts.

Elle est utile dans les monorepos où certains packages locaux sont injectés dans d'autres projets.

Exemple :

syncInjectedDepsAfterScripts:
  - build

Dans cet exemple, pnpm resynchronise les dépendances injectées après l'exécution du script build.

Note

Cette configuration permet d'éviter que des projets consommateurs utilisent une version obsolète d'une bibliothèque locale après un build.

catalog

La clé catalog permet de centraliser les versions des dépendances externes utilisées dans le monorepo.

Exemple :

catalog:
  zod: ^3.24.0
  "@nestjs/common": ^11.0.0
  "@nestjs/core": ^11.0.0

Une fois une dépendance déclarée dans le catalog, les projets peuvent l'utiliser avec catalog:* dans leur package.json.

Exemple :

{
  "dependencies": {
    "zod": "catalog:*"
  }
}

L'intérêt est de garder une version unique et cohérente de la dépendance dans tout le monorepo.

Tip

Utilisez catalog:* pour les dépendances externes dont la version doit être centralisée au niveau du workspace.

Installer une bibliothèque locale

Les bibliothèques locales du monorepo doivent être référencées avec workspace:*.

Exemple :

{
  "dependencies": {
    "@feelbat/kafka": "workspace:*"
  }
}

Cela indique à pnpm que la dépendance doit être résolue depuis le workspace local et non depuis le registre npm.

Warning

Utilisez workspace:* uniquement pour les packages internes au monorepo. Pour une dépendance externe, utilisez une version classique ou catalog:* si elle est gérée par le catalog.

workspace:* vs catalog:*

Syntaxe	Usage	Exemple
workspace:*	Dépendance interne au monorepo	@feelbat/kafka
catalog:*	Dépendance externe versionnée dans le catalog	zod

Résumé :

• workspace:* pointe vers un package local du monorepo.
• catalog:* pointe vers une version centralisée dans pnpm-workspace.yaml.

Supprimer une dépendance

Pour supprimer une dépendance d'un projet spécifique :

pnpm remove <package-name> --filter @feelbat/<project-name>

Exemple :

pnpm remove zod --filter @feelbat/auth

Commandes utiles

Afficher pourquoi une dépendance est installée :

pnpm why <package-name>

Lister les dépendances :

pnpm list

Afficher les dépendances obsolètes :

pnpm outdated

Bonnes pratiques

• Utilisez --filter lorsque vous ajoutez une dépendance à un projet précis.
• Utilisez -w uniquement pour les dépendances globales au workspace.
• Utilisez workspace:* pour les packages internes.
• Utilisez catalog:* pour les dépendances externes centralisées.
• Évitez de dupliquer les versions d'une même dépendance dans plusieurs package.json.
• Supprimez les dépendances inutilisées.

À éviter

Évitez d'ajouter une dépendance sans préciser le contexte :

pnpm add zod

Préférez :

pnpm add zod --filter @feelbat/auth

Ou, si la dépendance est globale au workspace :

pnpm add -D zod -w

À retenir

• pnpm gère toutes les dépendances du monorepo.
• pnpm-workspace.yaml définit les packages du workspace et les versions centralisées.
• workspace:* sert aux dépendances internes.
• catalog:* sert aux dépendances externes centralisées.
• Les commandes pnpm add doivent toujours préciser le contexte d'installation.