Laissez npm choisir le registre selon la portée du paquet, pas le VPN

Se connecter au VPN ne devrait pas signifier modifier le réglage de registre de npm deux fois par jour. Une entrée de portée dans un fichier de configuration au niveau du projet peut envoyer les paquets de l’entreprise vers un registre et tout le reste vers le public, sans basculement et sans écrasement oublié un vendredi après-midi. Le hic, c’est que cela ne résout que le nommage ; le routage, les identifiants et la priorité de configuration sont trois choses distinctes qui échouent chacune à sa manière.

Deux noms, deux destinations

Un nom de paquet npm a soit une portée, soit il n’en a pas. Un nom avec portée commence par un arobase et un identifiant de portée, et c’est cet identifiant que la configuration peut associer. Rien d’autre dans le paquet n’importe pour l’association. Le registre ne voit jamais une requête selon que le paquet est interne ou public ; il ne voit qu’un nom.

Ainsi, le fichier ci-dessous exprime deux intentions en trois lignes : les paquets publics vont au registre public, et les paquets sous la portée de l’entreprise vont au registre de l’entreprise avec un jeton pour cet hôte.

registry=https://registry.npmjs.org/
@acme:registry=https://packages.corp.example/
//packages.corp.example/:_authToken=${NPM_TOKEN}

Remplacez la portée, l’hôte et le nom de la variable par ce que l’organisation fournit réellement. La structure compte, pas les valeurs d’exemple. Deux lignes de configuration portent toute la politique, et c’est pourquoi elles valent la peine d’être comprises plutôt que copiées.

Gardez l’association et le réseau dans des compartiments séparés dans votre tête. Une entrée de portée ne peut pas rendre accessible un hôte inaccessible, et un tunnel qui fonctionne ne peut pas dire à npm à quel registre appartient un paquet.

Écrivez le fichier dans le bon ordre

Placez le fichier du projet en premier dans votre raisonnement même si npm lit plusieurs fichiers. Un .npmrc dans le répertoire du projet est celui que vos collègues héritent via le dépôt, il doit donc exprimer la politique partagée plutôt que votre jeton personnel. Ce fichier est aussi celui qu’un relecteur lira. Gardez-le assez petit pour être relu d’un coup d’œil.

Laissez la ligne registry par défaut pointer vers le registre public, sauf si l’organisation en a décidé autrement. La supprimer rend la machine dépendante de ce que dit le fichier au niveau utilisateur, et c’est exactement le genre de dépendance implicite qui produit des résultats différents sur deux portables.

La ligne de portée n’est pas un joker. Un nom hors de la portée continue d’utiliser la valeur par défaut, et c’est le comportement que vous voulez pour chaque dépendance que vous n’avez pas écrite vous-même.

Vérifiez ce à quoi le fichier se résout avant de le valider, en utilisant un nom de paquet jetable plutôt qu’une installation réelle, pour qu’une erreur ne coûte rien.

Les identifiants appartiennent à un hôte, pas à un projet

Les entrées d’authentification sont liées à un hôte de registre et, là où le registre l’exige, à un chemin. C’est pourquoi la ligne de jeton commence par la double barre oblique et l’hôte plutôt que par la portée. Dès que vous voyez l’hôte à cette place, le reste de la ligne cesse de ressembler à une ponctuation arbitraire. C’est une adresse, et le jeton y est attaché.

Utiliser une variable d’environnement garde le jeton littéral hors du fichier dans le dépôt. Cela ne rend pas le jeton invisible partout ; il apparaît toujours dans l’environnement du processus, et une commande qui imprime la configuration peut le révéler.

Fournissez la variable via le mécanisme local ou de CI approuvé par l’organisation, et ne collez jamais un vrai jeton dans un exemple susceptible d’être copié dans la documentation.

Si deux registres sont en jeu, chacun reçoit sa propre entrée. Un seul réglage de jeton non qualifié est au mieux ambigu et au pire envoyé au mauvais hôte.

Quand le mauvais registre gagne

La configuration est en couches, et la valeur effective n’est pas forcément celle du fichier que vous venez de modifier. Les réglages du projet, ceux de l’utilisateur, les réglages globaux et les variables d’environnement y participent tous. Cette superposition explique pourquoi un correctif fonctionne sur votre machine et pas dans le conteneur d’un collègue. C’est aussi pourquoi il vaut la peine d’imprimer la valeur effective avant d’en discuter.

La variable d’environnement est le coupable habituel en CI, où une tâche définit le registre une fois et chaque étape suivante en hérite. Le deuxième cas le plus courant est un fichier au niveau utilisateur sur la machine d’un développeur qui écrase ce que dit le dépôt.

Imprimez la configuration effective et le registre résolu pour un nom avec portée et un nom sans portée avant de déboguer quoi que ce soit d’autre. Si ces deux réponses sont ce que vous attendez, le problème est le réseau ; sinon, le problème est la configuration et aucun travail sur le VPN n’aidera.

Liste de vérification avant de valider

Confirmez que le nom de portée correspond aux paquets réellement publiés, que le registre par défaut est explicite et que la ligne de jeton nomme le bon hôte. Une faute de frappe dans la portée produit l’échec le plus étrange de tous, car le paquet se résout depuis le registre public et renvoie le module de quelqu’un d’autre portant le même nom. Vérifiez le nom avant de déboguer le jeton.

Confirmez que le registre privé est joignable depuis la machine dans le contexte qui exécute l’installation, pas seulement depuis votre navigateur. Cette distinction compte lorsqu’un proxy ou un conteneur a un routage différent de votre shell.

Confirmez ensuite le comportement sur une copie propre sans paquets en cache. Une installation fraîche est le seul test qui montre ce qu’un nouveau collègue vivra.