Comment publier des packages NPM privés d'entreprise sur GitLab ? Un guide complet de configuration pnpm

Imaginez que vous êtes un chef de cuisine. Pour garantir que tous les restaurants de votre chaîne produisent les mêmes plats délicieux, vous avez mis au point une série de « sauces secrètes ». Vous voulez que ces sauces soient envoyées à chaque succursale, mais vous ne pouvez pas laisser n’importe quel passant les emporter.

Dans le monde du développement logiciel, ces sauces secrètes sont les « packages privés » internes à l’entreprise.

À mesure que les projets se multiplient, vous avez probablement déjà ressenti cette frustration : dupliquer le même composant d’interface utilisateur ou la même fonction utilitaire dans chaque projet, ou lutter avec les Git Submodules au point de remettre en question vos choix de vie. En fait, tout ce dont vous avez besoin est un « Garde-manger privé (Private NPM Registry) ». Aujourd’hui, nous allons voir comment utiliser pnpm pour publier des packages sur GitLab, afin que les membres de l’équipe puissent les installer comme des packages open source avec une seule commande.

Pourquoi avez-vous besoin de packages privés et de Scopes ?

Dans l’univers Node.js, les packages privés doivent avoir un « nom de famille » : c’est le Scope.

Par exemple, si votre entreprise s’appelle @my-company, le nom de votre package pourrait ressembler à ceci : @my-company/ui-kit. Avec ce nom de famille, lorsque pnpm le verra, il ne cherchera pas au hasard sur npmjs.org. Au lieu de cela, il se dirigera directement vers les points de coordination de votre entreprise que vous aurez spécifiés.

Décision clé : Group Level vs Project Level

Dans GitLab, c’est comme décider où stocker vos condiments :

Niveau	Description
Project Level (Niveau Projet)	Comme le coffre-fort personnel d’un chef, utilisable uniquement pour certains plats. C’est plus fastidieux à configurer, car chaque package nécessite une configuration indépendante.
Group Level (Niveau Groupe)	C’est le concept de « Cuisine centrale » — hautement recommandé ! Configurez-le une fois, et des dizaines, voire des centaines de packages au sein du même groupe pourront partager les mêmes paramètres et identifiants.

Configuration du « Passeport » : Access Tokens et variables d’environnement

Pour entrer dans le grenier souterrain, vous devez d’abord obtenir une « carte d’accès ».

Allez dans Settings > Access Tokens sur GitLab.
Demandez un Token, en cochant les permissions read_api (pour le téléchargement) et write_package_registry (pour la publication).
Important : Une fois que vous avez le Token, ne l’écrivez jamais directement en dur dans votre code ou votre fichier .npmrc ! C’est comme laisser la clé du coffre-fort sur la porte.

L’approche la plus professionnelle consiste à le cacher dans des « variables d’environnement ». Ajoutez cette ligne à votre terminal Mac ou Linux (par exemple, ~/.zshrc) :

export GITLAB_TOKEN="votre_token_GitLab"

De cette façon, le système joindra automatiquement les identifiants pour vous, ce qui rend l’opération à la fois sûre et pratique.

Paramètres de navigation : L’essence du `.npmrc`

Ensuite, nous allons créer une carte de navigation, .npmrc, à la racine du projet pour dire à pnpm où aller :

# Pour tout ce qui commence par @my-company, allez sur GitLab
@my-company:registry=https://gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/

# Configurer l'authentification par carte d'accès (lecture de la variable d'environnement que nous venons de définir)
//gitlab.com/api/v4/groups/<YOUR_GROUP_ID>/-/packages/npm/:_authToken="${GITLAB_TOKEN}"

Il suffit de remplacer le Group ID de votre entreprise, et la voie est tracée !

Le dernier kilomètre avant la publication : l’art de l’emballage

Beaucoup de gens se précipitent pour publier après avoir configuré la connexion, pour finalement télécharger accidentelment des fichiers de test ou même des configurations secrètes. C’est là que le champ files dans package.json s’avère utile.

C’est un concept d’« allowlist » (liste d’autorisation) :

{
  "name": "@my-company/lib-1",
  "files": [
    "dist"
  ],
  "publishConfig": {
    "registry": "https://gitlab.com/api/v4/projects/<YOUR_PROJECT_ID>/packages/npm/"
  }
}

Paramètre	Description
`files`	Dites explicitement au système que je ne veux publier que l’essence compilée dans `dist`, en laissant derrière moi tout le reste.
`publishConfig`	C’est une double assurance, garantissant que ce package ne sera jamais publié accidentellement sur la place publique (npmjs.org).

Avant de publier, il est recommandé d’utiliser la commande pnpm pack pour déballer et vérifier le contenu localement. Une fois que tout semble correct, lancez pnpm publish en toute confiance !

Conclusion

Construire un garde-manger privé n’est pas difficile. Les clés sont les suivantes :

Demander un Token et le protéger avec des variables d’environnement.
Configurer la bonne carte de navigation .npmrc.
Utiliser le champ files dans package.json pour une expédition précise.

En maîtrisant ce flux de travail, vous pouvez rendre la réutilisation du code de votre entreprise professionnelle, sûre et élégante. Maintenant, allez construire votre propre cuisine centrale !