Comprendre le rôle du fichier .npmrc
Le ficheir .npmrc (npm run configuration) est un fichier de type clé-valeur qui dicte le comportement du gestionnaire de paquets npm. Son utliisation principale réside dans la définition des points de terminaison (registries) pour le téléchargement des dépendances, permettant ainsi de router les requêtes vers des serveurs privés ou des miroirs publics.
Hiérarchie de résolution des configurations
Lorsqu'une commande npm est exécutée, le gestionnaire fusionne les configurations provenant de plusieurs sources. L'ordre de priorité, du plus spécifique au plus général, est le suivant :
- Configuration du projet (
/chemin/vers/projet/.npmrc) - Configuration de l'utilisateur (
~/.npmrc) - Configuration globale (
$PREFIX/etc/npmrc) - Configuration intégrée à npm (fournie avec l'installation de Node.js)
Vous pouvez localiser ces fichiers à l'aide des commandes suivantes :
# Localiser le fichier de configuration utilisateur
npm config get userconfig
# Identifier le préfixe global pour la configuration système
npm config get prefix
# Trouver le chemin de l'exécutable npm
command -v npm
Définir les registres de paquets
Configuration au niveau du projet
C'est la méthode recommandée pour les projets d'équipe. Placé à la racine du dépôt, ce fichier garantit que tous les développeurs utilisent les mêmes sources, sans altérer leur environnement local. Les clés sont définies au format clé=valeur.
# Définition du registre principal
registry=https://registry.npmjs.org/
# Routage spécifique pour les paquets sous le scope @mon-entreprise
@mon-entreprise:registry=https://npm.pkg.github.com/
Configurations utilisateur et globale
Pour modifier les paramètres par défaut de votre machine, vous pouvez éditer directement le fichier ~/.npmrc ou utiliser l'interface en ligne de commande. L'ajout du drapeau -g (ou --global) bascule la modification vers le niveau système.
# Appliquer un miroir au niveau utilisateur
npm config set registry https://mirrors.cloud.tencent.com/npm/
# Supprimer une entrée spécifique
npm config delete registry
# Écraser la configuration pour tous les utilisateurs du système
npm config set registry https://mirrors.cloud.tencent.com/npm/ -g
Substitution éphémère via CLI
Il est possible de contourner temporairement les fichiers de configuration en passant l'URL directement dans la commande. Cette aprpoche est utile pour des scripts ponctuels, mais elle est moins maintenable qu'un fichier .npmrc dédié.
npm install lodash --registry=https://mirrors.cloud.tencent.com/npm/
Récapitulatif des commandes de gestion
Voici les opérations fondamentales pour manipuler ces paramètres :
# Assigner une valeur à une clé (ajouter -g pour le niveau global)
npm config set <clé> <valeur>
# Consulter la valeur effective d'une clé
npm config get <clé>
# Retirer une clé de la configuration
npm config delete <clé>
# Afficher l'ensemble des paramètres actifs (ajouter -l pour les détails)
npm config list
# Ouvrir le fichier de configuration utilisateur dans l'éditeur par défaut
npm config edit
Compatibilité avec les gestionnaires alternatifs
Il est important de noter que des outils alternatifs comme Yarn (v1) et pnpm sont conçus pour lire et respecter les directives du fichier .npmrc. Cela évite d'avoir à dupliquer la configuration pour chaque gestionnaire de paquets.
Résolution des conflits de registres
Une erreur fréquente survient lorsqu'un projet exige un registre privé pour certains paquets scopés, mais que le registre par défaut pointe vers un miroir public incompatible. Cela se manifeste souvent par un échec de résolution avec un code de sortie non nul (ex: exit code 1).
Pour corriger cela, assurez-vous que l'URL du registre privé est correctement déclarée. Si l'erreur persiste après la modification du .npmrc, le cache local ou le fichier de verrouillage peuvent être corrompus. Procédez alors à un nettoyage complet :
# Suppression du cache, du verrouillage et des dépendances installées
rm -rf node_modules package-lock.json yarn.lock
npm cache clean --force
# Réinstallation propre
npm install