Scope npm

Dans l’article précédent, nous avons parlé brièvement des scope npm, cet article a pour but d’approfondir cette partie.

Préambule

Dans le langage courant, npm désigne à la fois le client npm et le registre npm. Nous serons donc prudents quand à distinguer les usages en précisant “registre npm” pour parler du registre, et en utilisant npm sans descriptif pour parler du client.

Le client et le registre sont d’ailleurs suffisamment distincts pour que de multiples clients alternatifs existent tout en gardant le même registre (yarn, pnpm…). Ces clients utilisent aussi le package.json sans changement, et ne changent donc rien au contenu de l’article.

Comment créer un scope npm

Un scope est défini simplement en l’indiquant dans le nom du paquet (propriété name du package.json), il est au début, précédé d’un @, et séparé du nom par /. Faisant partie du nom, il est soumis aux mêmes limites:

• Pas plus de 214 caractères (scope + nom)
• Ne peux pas commencer par . (mais contrairement aux noms, peut commencer par _ !)
• Lettres minuscules seulement
• Pas de caractère considéré comme dangereux dans une url (RFC 3986). Il vaut donc mieux se limiter aux lettres, chiffres, et séparateurs (-, _)

Ainsi, créer un paquet test dans le scope adikts, le nom de mon paquet serait: @adikts/test

Si vous voulez utiliser ce scope sur le registre npm, il vous faudra créer une organisation dont le nom sera le scope. Si le nom que vous vouliez prendre est déjà pris, il vous faudra en prendre un autre. La possession d’une organisation étant gratuite, réserver le ou les scopes autour de votre nom reste une bonne idée même si vous n’avez pas de plan immédiat à publier des paquets sur le registre.

Pourquoi utiliser un scope npm ?

L’avantage principal d’utiliser un scope npm est que le scope est réservé à votre organisation. Vous ne pouvez pas publier dans le scope de quelqu’un d’autre, de la même manière que personne ne peut publier dans votre scope sans votre autorisation.

Dans le contexte d’un registre mondial comme npmjs.com, cela a pour avantage de maintenir votre identité, et d’éviter que quelqu’un ne fasse passer son paquet comme l’un des vôtres.

Si je cherche un paquet lié à react, je vois que les trois premiers sont react, react-dom et react-dropzone. Il pourrait sembler que react-dropzone est développé par la même organisation que celle qui maintient react et react-dom. Il faut regarder la liste des auteurs pour constater que react-dropzone est l’œuvre d’un développeur indépendant.

$ npm search react
NAME                      | DESCRIPTION          | AUTHOR          | DATE       | VERSION  | KEYWORDS
react                     | React is a…          | =gaearon…       | 2022-06-14 | 18.2.0   | react   
react-dropzone            | Simple HTML5…        | =rolandjitsu…   | 2022-10-12 | 14.2.3   | react-component react d
react-dom                 | React package for…   | =gaearon =zpao… | 2022-06-14 | 18.2.0   | react

À l’inverse, si je recherche angular, je peux voir qu’un scope angular existe, et sait immédiatement que tout les paquets dans ce scope sont bien maintenus par la même équipe. Un paquet tel que angular-ui-bootstrap est immédiatement identifié comme venant d’une autre équipe car n’étant pas dans le scope.

$ npm search angular
NAME                      | DESCRIPTION          | AUTHOR          | DATE       | VERSION  | KEYWORDS               
@angular/material         | Angular Material     | =angular…       | 2023-01-11 | 15.1.0   | angular material materi
@angular/cdk              | Angular Material…    | =angular…       | 2023-01-11 | 15.1.0   | angular cdk component d
@angular/cli              | CLI tool for Angular | =angular…       | 2023-01-12 | 15.1.1   | Angular CLI Angular Dev
@angular-devkit/core      | Angular DevKit -…    | =angular…       | 2023-01-12 | 15.1.1   | Angular CLI Angular Dev
angular-ui-bootstrap      | Native AngularJS…    | =icfantv…       | 2017-10-14 | 2.5.6    | angularjs angular boots

Je ne publie pas mes paquets sur npm, mais sur un repository privé

Les scopes seront quand même utiles, puisque npm permet de configurer les registres via les scopes.

Par exemple, si Adikts maintient son propre registre npm privé sur npm.adikts.io, et que nous décidons d’utiliser le scope @adikts, je peux configurer npm pour automatiquement utiliser ce registre pour ce scope:

npm login --registry=http://npm.adikts.io --scope=@adikts
npm config set @adikts:registry http://npm.adikts.io

Ainsi, toutes les commandes impliquant le scope @adikts utiliseront automatiquement le registre privé:

npm init
npm install -D express                      # Install the package express from the global registry
npm install -D @adikts/test                 # Install the package @adikts/test from http://npm.adikts.io
npm pkg set 'name'='@adikts/my-project'     # Set the package name to "@adikts/my-project"
npm publish                                 # The package name set the scope @adikts, so it will be published on http://npm.adikts.io

A retenir

Les scopes peuvent servir que vous utilisiez le registre npm ou des registres privés. Ils ne coûtent rien. Il s’agit juste d’une question de nommage. Ils permettent de faciliter l’organisation, la sécurité et la configuration des paquets dans l’immédiat et dans le futur.