«npm WARN requires a peer» : comment corriger et comprendre l'essence de l'erreur

Introduction : pourquoi npm vous crie dessus ?

Avez-vous déjà lancé npm install et vu quelque chose comme ceci ?

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed. You must install peer dependencies yourself.

Ça vous dit quelque chose ? Si oui, vous n'êtes pas seul. Cette question sur Stack Overflow a rassemblé des milliers de vues et des dizaines de commentaires de développeurs qui, comme vous, voulaient simplement installer un paquet et ont eu mal à la tête. Aujourd'hui, nous allons comprendre ce que sont les peer dependencies, pourquoi npm insiste tant pour les installer et comment travailler correctement avec elles dans les projets TypeScript. Et oui, ce ne sera pas une documentation ennuyeuse, mais une analyse vivante avec des exemples de code.

C'est parti !

Que sont les peer dependencies et pourquoi sont-elles nécessaires ?

Imaginez que vous assemblez un puzzle. Vous avez une image principale (votre projet) et plusieurs pièces (les paquets). Certaines pièces s'emboîtent parfaitement, mais seulement si vous utilisez le bon cadre. Dans le monde de npm, ce « cadre » est une peer dependency.

Une peer dependency (ou « dépendance homologue ») est une exigence d'un paquet selon laquelle une bibliothèque spécifique doit être installée dans le projet, mais le paquet lui-même ne l'installera pas. Pourquoi ? Parce que cette bibliothèque devrait déjà être présente chez vous, et le paquet « s'associe » simplement avec elle, sans créer de doublons.

Par exemple, le paquet ts-patch (un outil populaire pour TypeScript) exige que typescript soit installé dans le projet. Mais ts-patch n'installe pas TypeScript lui-même — il suppose que vous l'avez déjà ajouté. Si TypeScript n'est pas présent, npm émet cet avertissement.

Pourquoi est-ce important pour les projets TypeScript ?

TypeScript n'est pas seulement un langage, c'est un écosystème. De nombreux paquets (par exemple, @types/react, ts-loader, eslint-plugin-typescript) fonctionnent au-dessus de TypeScript. Si vous avez installé la version 5.0 de TypeScript et que le paquet nécessite la version 4.0+, tout va bien. Mais si TypeScript n'est pas du tout installé, les problèmes commencent.

Voici un exemple concret de la vie réelle. Supposons que vous écriviez un petit script en TypeScript et que vous utilisiez ts-patch pour la transformation du code. Vous lancez :

npm install ts-patch --save-dev

Et vous obtenez :

npm WARN ts-patch@3.2.1 requires a peer of typescript@>=4.0 but none is installed.\nYou must install peer dependencies yourself.

Que faire ? Paniquer ? Non. Installez simplement TypeScript :

npm install typescript --save-dev

Problème résolu. Mais que faire si vous avez déjà TypeScript, mais une version différente ? C'est là que les choses deviennent intéressantes.

Comparaison des approches : comment installer les peer dependencies

Il existe plusieurs façons de gérer cette erreur. Comparons-les sur l'exemple d'un projet TypeScript.

Approche 1 : Installation manuelle (classique)

La méthode la plus simple et la plus fiable est de lire l'avertissement et d'installer manuellement le paquet requis. Vous voyez que typescript@>=4.0 est requis, et vous l'ajoutez :

npm install typescript@^4.0 --save-dev

Avantages :

\n
• Contrôle total sur la version.
\n
• Pas de surprises cachées.
\n

Inconvénients :

\n
• Il faut lire attentivement les messages de npm.
\n
• S'il y a beaucoup de paquets, le processus devient répétitif.
\n

Cette approche est idéale pour les petits projets où vous savez exactement de quelles dépendances vous avez besoin.

Approche 2 : Installation automatique avec npx ou des plugins

Certains outils, comme npm-check ou install-peerdeps, peuvent installer automatiquement toutes les peer dependencies pour un paquet spécifique. Installez l'utilitaire globalement :

npm install -g install-peerdeps