Pour harmoniser une dépendance entre des paquets npm sur un Mac, commencez par comparer les plages de versions dans le package.json de chaque workspace, choisissez quelle plage de versions commune convient à chaque paquet, puis mettez à jour chaque workspace concerné et régénérez le fichier lockfile racine. Les workspaces npm peuvent cibler des paquets depuis la racine du dépôt, mais ils ne fournissent pas de commande intégrée qui analyse chaque manifeste et rend automatiquement les versions des dépendances identiques.

1. Vérifier que le dépôt utilise les workspaces npm

Dans le Terminal, déplacez-vous à la racine du dépôt et inspectez sa configuration :

cd "/path/to/your/repository"
npm --version
npm pkg get workspaces

Le fichier package.json racine doit définir les chemins des workspaces, et chaque paquet doit avoir son propre package.json. La fonctionnalité de workspaces de npm lie ces paquets locaux lors de l'installation et permet aux commandes de cibler un ou plusieurs workspaces par nom ou par chemin. Si npm pkg get workspaces ne renvoie rien, confirmez le gestionnaire de paquets et la structure du dépôt avant d'utiliser les commandes d'espace de travail de npm. npm Workspaces

2. Comparer les déclarations de dépendances

Recherchez la dépendance que vous souhaitez harmoniser dans les manifestes suivis. Par exemple, dans le Terminal de macOS, vous pouvez utiliser grep sans installer d'outil supplémentaire :

grep -n '"typescript"' package.json packages/*/package.json

Remplacez typescript par le nom de la dépendance. Il s'agit d'une vérification textuelle rapide ; examinez donc les sections correspondantes dans chaque manifeste pour voir si le paquet figure sous dependencies, devDependencies, peerDependencies ou optionalDependencies. Ces champs décrivent des rôles différents ; ne déplacez pas une dépendance de l'un à l'autre simplement pour faire correspondre les chaînes de version. Pour un inventaire plus complet, inspectez le manifeste de chaque workspace dans votre éditeur ou utilisez la commande de listage de npm prenant en charge les workspaces :

npm ls typescript --workspaces --depth=0

Les plages des manifestes et l'arborescence installée répondent à des questions différentes : les premières indiquent ce que chaque paquet autorise, tandis que npm ls rapporte l'état des dépendances installées. Le fichier lockfile de npm enregistre les versions résolues, mais il ne remplace pas les plages acceptables déclarées dans chaque package.json. npm ls package-lock.json and npm install

3. Choisir une politique de version compatible

Choisissez une version qui satisfait les exigences des consommateurs et la politique de support du dépôt. Une plage de versions partagée signifie que les paquets expriment le même ensemble autorisé ; cela ne garantit pas que toutes les copies imbriquées ou transitives se résolvent en une seule copie installée. Vérifiez les exigences des dépendances de pairs (peer dependencies) et les notes de version pour détecter d'éventuels changements cassants avant de faire passer des paquets à une version majeure supérieure. Si les consommateurs ont besoin d'une plage de compatibilité plus large, harmoniser sur la même chaîne exacte peut être inapproprié ; convenez plutôt d'une politique de plage équivalente.

Par exemple, pour définir un outil de développement sur la même version exacte dans deux workspaces nommés web et api, exécutez ceci depuis la racine :

npm install --save-dev --save-exact typescript@5.8.3 --workspace=web --workspace=api

Utilisez la version sélectionnée par votre projet ; 5.8.3 n'est ici qu'un exemple. La commande d'installation de npm accepte les sélecteurs de workspace et enregistre le paquet dans le manifeste de chaque paquet sélectionné. --save-exact écrit une version exacte plutôt que l'opérateur de plage habituel de npm. Pour une dépendance d'exécution, utilisez la catégorie d'enregistrement appropriée, comme --save-prod, à la place de --save-dev. npm install

Répétez l'opération avec des sélecteurs de workspace supplémentaires ou exécutez la commande pour chaque workspace. Ne supposez pas qu'une installation au niveau racine met à jour le manifeste de chaque paquet : ciblez explicitement les paquets dont les déclarations doivent changer. Le paquet racine peut également être inclus délibérément avec --include-workspace-root lorsqu'il doit déclarer la même dépendance.

4. Réinstaller, inspecter le diff et vérifier

Après avoir mis à jour les déclarations, lancez l'installation à la racine du dépôt afin que npm réconcilie l'arborescence des workspaces et le lockfile :

npm install
npm ls typescript --workspaces --depth=0
git diff -- package.json package-lock.json packages/*/package.json

Vérifiez que chaque manifeste ciblé comporte la déclaration convenue et que la modification du lockfile correspond aux attentes. Exécutez les scripts de build ou de test pertinents du dépôt ; npm ls seul ne garantit pas que le code fonctionne avec la version sélectionnée. Validez (commit) le package-lock.json racine lorsque le projet le suit, afin que les installations de l'équipe puissent reproduire l'arborescence résolue. npm package-lock documentation

Si npm signale une dépendance invalide ou un conflit de pairs (peer conflict), inspectez le paquet mentionné dans l'erreur plutôt que de forcer l'installation. Un workspace peut nécessiter une plage compatible différente, ou une autre dépendance peut imposer une exigence de pairs nécessitant un plan de mise à niveau délibéré.

Quand npm dedupe est utile

npm dedupe peut simplifier l'arborescence des dépendances installées en déplaçant les dépendances compatibles plus haut dans l'arborescence afin que les paquets puissent les partager. Il ne réécrit pas les plages de dépendances directes dans package.json, il ne peut donc pas harmoniser les déclarations à lui seul. Utilisez-le uniquement après avoir vérifié que les plages sont compatibles, puis examinez le diff du lockfile qui en résulte. npm dedupe

L'aboutissement le plus fiable repose sur une politique délibérée exprimée dans chaque manifeste de workspace concerné, un lockfile régénéré et la vérification des paquets affectés. Cela offre aux mainteneurs un historique clair de ce qui a été harmonisé et laisse visibles les contraintes incompatibles pour une décision distincte.

Sources