Comment créer un package NPM ?

Peut-être que vous avez travaillé dur sur du code de fond, qui apporte une fonctionnalité essentielle. Peut-être que vous avez du code que vous utilisez à plusieurs endroits, dans différents projets, et que vous copiez collez. Comment bien réutiliser ce code?

Si on le copie/colle, ce code devient difficile à gérer et compliqué à maintenir.

La solution est simple: utiliser un gestionnaire de librairie qui vous permet de centraliser ce code.

Chaque language (ou presque) dispose du sien. Dans le monde JavaScript, le gestionnaire de librairie (ou plus exactement de module) de référence s’appelle NPM ou Node Package Manager. Et dans cet article nous allons voir comment créer un package NPM pour pouvoir réutiliser son propre code, et partager son code avec la terre entière. (Qui évidemment n’attend que ça).

Dans ce guide, nous allons donc construire un module réutilisable en Typescript et le publier en tant que package Node.js.

J’utilise Typescript ici parce que ça permet d’être utilisable par ceux qui utilisent JavaScript ET ceux qui utilisent TypeScript, alors qu’un paquet JS pourrait être utilisé de manière propre seulement par ceux qui sont sous javascript.

Vous allez voir, c’est très simple et rapide.

Pour l’exercice, on ne va pas trop passer de temps sur le code spécifique que propose le module – on va juste créer une fonction simple qu’on va mettre dans le module NPM et qu’on va appeler depuis un autre projet.

Etape 1 : Créer un compte sur NPM

La première étape consiste tout simplement à se créer un compte sur NPM.

On va sur NPM, on s’enregistre avec son email et son mot de passe, et c’est fait.

Il faut évidemment aussi avoir installé Node JS et NPM en local sur son ordi.

J’imagine que si vous êtes en train de lire un article sur comment créer des package NPM c’est votre cas. Si non, Google est votre ami !

Il faut aussi avoir Typescript installé de manière globale, avec la commande :

npm install -g typescript

Etape 2 : Choisir un nom pour le module

NPM va nous demander de choisir un nom pour le module. C’est important de donner un nom unique pour quand on publie le module.

Si vous avez un nom génial en tête, vous vérifier s’il est pris avec la commande npm list.

Le site de NPM permet aussi de faire des recherches. Pour ma part je fais simplement préfixer le nom du paquet avec @kodaps

Etape 3 : créer le module

A présent, on crée le dossier dans lequel on veut mettre le module, et on y ouvre un terminal. Soit via la ligne de commande, soit directement depuis l’éditeur.

Là, je lance npm init. Le programme va nous poser un certain nombre de questions simples, ça va être l’occasion d’utiliser le nom génial qu’on a choisi en étape précédente.

Je vous conseille de choisir un numéro de version en 0.0.1 ou quelque chose de bas, parce que dès qu’on met à jour le packet sur NPM il faut incrémenter le numéro de version.

Du coup tant qu’on est en train d’expérimenter vaut mieux se laisser de la marge avant la version 1.0 qui, comme son nom l’indique, est sensé être pleinement fonctionnel.

Pour les autres options laissez la valeur par défaut pour le moment.

Etape 4 : ajouter le support du Typescript

Maintenant je vais ajouter le typescript au projet.

Je vais commencer par installer typescript comme dépendance dev du projet, en tapant

yarn add typescript

ou:

npm add typescript

Une fois que c’est fait, j’initialise typescript dans le dossier.

Du coup je lancer la commande tsc --init dans le dossier, ça va nous créer un fichier tsconfig.json .

L’idée c’est d’écrire du code typescript dans un dossier ./src, et on va “transpiler” ce code ver le Javascript, par exemple dans un dossier ./lib

Pour ce faire, j’ai une ou deux petites manipulation à faire dans le fichier tsconfig.json

Tout d’abord, je vais mettre décommenter la ligne avec declaration, ça va permettre au compilateur Typescript d’émettre les fichiers de type.

Ensuite, je vais définir le dossier outDir, le dossier de sortie, donc ici je vais mettre le dossier lib

A présent, après la déclaration des options de compilation, je vais configurer les fichiers que je prends en compte.

Donc je renseigner include avec un array qui contient juste le chemin vers src Et je fais une entrée exclude avec le dossier node_modules et les dossiers test

Alors à cette étape je serais tenté de lancer la compilation, mais il faut qu’on écrive du code d’abord !

Etape 5 écrire le code du module

Du coup, dans le projet je crée un dossier src

Dans ce dossier src je crée deux fichiers .ts : index et faker

Dans faker on va simplement créer et exporter une fonction du même nom qui retourne un tableau d’objets prénom / nom

Dans le fichier index, qui sert de point d’entrée à la librairie, on importe et on exporte cette fonction faker. L’idée c’est de rajouter dans ce fichier tous les exports publics du module.

A présent je lance la compilation, en ligne de commande dans le dossier, avec la commande « tsc »

A présent si on regarde dans le dossier lib, il y a des fichiers index et faker en version js et .d.ts, la version exécutable étant le code JS et les types le fichier .d.ts

A présent il reste un dernier petit détail à régler.

Si on ouvre le fichier package.json, il y a une entrée main qui désigne le point d’entrée. Notre main à nous est pas à la racine du projet mais dans le sous dossier lib, donc il faut l’indiquer.

Je vais aussi rajouter une entrée types au pluriel, à côté de « main », où je vais indiquer le chemin vers le fichier index.d.ts

Un dernier détail qui est tout sauf un détail, il faut indiquer à présent dans ce fichier package.json quels sont les fichiers à publier sur NPM.

Pour ça il y a une entrée « files » dans lequel on met un tableau qui contient juste le chemin « libs »

Ouf, nous voilà enfin prêts à publier notre module !

Et donc à l’etape 6 : la publication du module !

La première chose à faire c’est vérifier si l’utilitaire npm en ligne de commande est bien connecté au site NPM.

Pour ça je vais taper dans le terminal « npm whoami » avec le « who am I » en un seul mot.

Si je suis bien connecté il va m’indiquer le nom d’utilisateur avec lequel je suis connecté, si non il faut que je me connecte.

Pour faire ça je tape juste « npm login » et je me connecte avec mes identifiants que j’ai utilisés pour me connecter sur le site NPM en première étape.

A présent, on va (enfin !) publier le module

Pour ça, rien de plus simple, on tape npm publish

Ici, dans un premier temps, npm va râler parce que les package privés demandent d’être en mode payant. Mais moi je ne tiens pas à tout prix que mon package soit privé, donc je fais

npm publish --access public

A present, si je vais sur le site de NPM je vois dans ma console que mon package est bien publié. Je peux l’installer du coup dans un autre projet avec un yarn add ou npm i

Et je vois quand je l’importe que les types sont bien reconnus, et que tout a bien marché.

Yay !!

C’est la fête, non ? :)

A présent il me reste deux choses à faire.

Tout d’abord, je vais installer des outils comme Jest pour faire les test unitaires, et Lint et Prettier pour rendre mon code plus joli.

Et puis surtout il me reste, et il vous reste, à développer des fonctionnalités intéressantes à mettre dans mon package.

Et du coup, c’est à vous de jouer. A vos claviers.