Essayez-vous d’utiliser un paquet privé (Private Package) dans le projet de votre entreprise mais êtes bloqué sur la configuration .npmrc ?

Pourquoi obtenez-vous toujours 404 Not Found même après avoir défini le jeton (Token) ?

Lorsque l’entreprise a plusieurs équipes et plusieurs paquets (par exemple @frontend, @backend), comment gérez-vous .npmrc avec élégance ?

Briser les deux mythes de .npmrc

Pour comprendre .npmrc, vous devez d’abord comprendre comment il fonctionne.

Simplement, sa logique centrale ne concerne que deux choses : Mappage de portée (Scope Mapping) et Authentification.

1. Mappage de portée (Scope Mapping)

Cela dit à npm : Lorsque vous voyez un paquet commençant par @company, n’allez pas sur le npmjs.org officiel, allez sur notre GitLab Registry spécifié.

@company:registry=https://gitlab.com/api/v4/groups/100/-/packages/npm/

2. Authentification (Authentication)

Avec l’adresse, vous avez aussi besoin d’une clé. La clé est votre AuthToken.

Voici une règle super cruciale : L’URL du Registry et le chemin de l’AuthToken doivent “correspondre exactement”.

# ✅ Correct : Le chemin est exactement le même que le registry défini ci-dessus
//gitlab.com/api/v4/groups/100/-/packages/npm/:_authToken=${GITLAB_TOKEN}

# ❌ Incorrect : Chemin incompatible, cela causera un échec de permission
//gitlab.com/api/v4/:_authToken=${GITLAB_TOKEN}

Beaucoup de gens échouent dans la configuration souvent parce que le chemin a une barre oblique supplémentaire ou manque d’un niveau.

Enfer des dépendances et erreurs 404

La situation la plus douloureuse est : Vous installez le paquet A, qui dépend du paquet B (également privé), et ensuite npm crache un 404 Not Found.

Pourquoi cela arrive-t-il ? C’est parce que lorsque npm résout les dépendances, s’il n’y a pas de relation correcte, il se perd.

Surtout lorsque vous avez deux portées différentes (par exemple @team-a et @team-b) dans différents groupes GitLab, .npmrc devient extrêmement complexe et difficile à maintenir. De plus, différents Registries peuvent avoir besoin de différents jetons, gérer ces variables d’environnement est épuisant.

Y a-t-il un moyen plus intelligent ?

Solution recommandée : Unified Download Group Registry & Independent Publish Project Registry

Pourquoi faire ça ?

Configuration en action

Vous pouvez copier directement ce modèle :

N’oubliez pas de confier la tâche de protéger le Jeton aux variables d’environnement, ne codez absolument pas le Jeton en dur dans le code !

# .npmrc
# @company scope utilise le registry au niveau du groupe
# Tous les paquets @company/* seront installés depuis ce registry
@company:registry=https://gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/

# Configuration d'authentification GitLab npm registry
# Utiliser le jeton d'authentification commun gitlab.com (couvre toutes les demandes au niveau du groupe et du projet)
//gitlab.com/api/v4/groups/YOUR_GROUP_ID/-/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}
# Utiliser le registry du projet pour publier des paquets
//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=${GITLAB_NPM_TOKEN}


# Les autres paquets publics vont toujours au registry officiel
registry=https://registry.npmjs.org/

Configurez publishConfig dans package.json pour publier le paquet dans le GitLab Project Registry correspondant.

{
  "name": "@company/my-package",
  "publishConfig": {
    "@company:registry": "https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
  }
}

Conclusion

Grâce à la stratégie de “Unified Download Group Registry” et “Independent Publish Project Registry”, nous pouvons réduire considérablement les coûts de maintenance et rendre le flux de développement plus fluide.

En maîtrisant ces logiques, GitLab NPM Registry sera un puissant assistant dans le processus de développement de votre entreprise !