Comment créer et publier votre premier module Node.js

Posted on:2 mai 2017 at 02:00

Vous avez sûrement déjà eu l’occasion d’utiliser différents modules par l’intermédiaire de npm pour Node.js. Aujourd’hui nous allons voir comment créer le nôtre puis, par la suite, le mettre en ligne sur le dépôt npm pour que des personnes puissent le télécharger simplement par la suite.

Pour cet article, nous allons faire un petit module très simple. Voir à quoi ressemble le fichier de configuration correspondant, comment mettre en ligne sur npm ainsi que mettre en place un texte descriptif. Pour vous faire une idée, voilà un module que j’ai réalisé et qui se trouve en ligne https://www.npmjs.com/package/sg-autorepondeur, à la fin de cet article vous aurez vous aussi une page sur le site npmjs.com ainsi que la possibilité de télécharger votre module via une simple commande dans votre terminal ! Let’s Go !

Pré-requis

Quelques pré-requis sont nécessaires pour suivre cet article, mais rien d’insurmontable je vous rassure !

Une fois ses conditions réunies, il ne nous reste plus qu’à attaquer le projet en lui-même ! J’insiste, vérifier de bien avoir la dernière version de npm d’installer sur votre machine, sinon cela pourrait pauser problème lors de la mise en ligne du module.

Configuration de npm

La première étape va simplement consister à donner à npm les informations nécessaires à notre profil. Je précise que ses informations seront disponibles publiquement sur la description du module. Faites donc attention de bien les remplir correctement et surtout de la façon dont vous le souhaitez.

Pour cela, la première étape consiste à ouvrir votre invité de commandes (cmd pour Windows) puis de rentrer les commandes suivantes, en modifiant bien entendu avec vos informations :

npm set init.author.name "Blog-Programmeur"
npm set init.author.email "[email protected]"
npm set init.author.url "https://blog-programmeur.fr/"

Ses informations seront enregistrées dans votre environnement, cela signifie que lors de la création du module / package Node.js, elles seront utilisées par défaut. Bien entendu, rien ne vous empêche de les modifiers à tout moment ou pour un projet en particulier.

Pour se connecter à votre compte npm sur votre machine, il vous suffit d’exécuter la commande qui suit. Votre email ainsi que votre mot de passe vous sera demandé. Je précise que, lorsque vous allez taper votre mot de passe, ne vous inquiétez pas si aucune étoile ”*****” n’apparaît, vous tapez bien le mot de passe mais, aucun caractère visible ne vous l’indiquera. Les linuxiens ne seront pas dépaysés.

npm login

Création d’un module npm

Nous allons donc maintenant créer notre premier module npm, je vous invite à vous rendre dans le répertoire de vos projets Node.js et créer un dossier pour votre extension, rentrer dedans puis effectuer la commande suivante dans votre invité de commandes npm init. Plusieurs informations vous seront demandées (voir image ci-dessous). Nous pourrons les modifier par la suite donc pas de panique si vous faites une erreur.

Juste une petite parenthèse concernant la licence, l’abréviation de celle-ci vous est demandée lors de la création de votre projet. Pour ma part j’opte régulièrement, et je vous conseille de faire de même, pour une licence MIT. Cela signifie que le projet est 100% Open Source et que quiconque peut faire ce qu’il souhaite avec. Pour plus d’informations sur les différentes licences qui existent rendez-vous ici.

Configuration du module

Un fichier, du nom de package.json vient normalement d’apparaître. En l’ouvrant avec votre éditeur de texte préférer, vous aller voir que celui-ci contient les différentes informations, concernant notre projet, que nous avons renseigné précédemment. S’il vous le souhaitait,  vous pouvez donc à partir de ce fichier modifier tout ce que vous souhaitez.

Je pense que le fichier de configuration parle de lui-même :

Cependant, il existe d’autres paramètres qui peuvent être ajoutés au fichier de configuration, nous allons en voir deux assez importants. L’un pour définir une version minimum de Node.js sur laquelle votre module peut fonctionner ainsi que définir des dépendances (si votre module est lui-même dépendant d’un autre module).

Spécifiez une version minimale de Node.js

Il peut être nécessaire parfois de définir une version minimum de Node.js pour votre module. Pour éviter des problèmes de compatibilité ou si vous souhaitez simplement ne pas soutenir une ancienne version. Pour ce faire, il vous suffit de rajouter la ligne suivante dans le fichier de configuration du module, c’est-à-dire package.json.

"engines": {
  "node": ">=4.2.4"
},

Spécifiez des dépendances

Il est très probable que, si vous réalisez des modules complexes, ayez besoin d’autres modules npm pour réaliser le vôtre. Il est donc important de définir les différentes dépendances dans le fichier de configuration. De cette façon npm installera automatiquement les dépendances en même temps que votre module quand une personne décidera de l’installer. Si vous ne faites pas cela, les dépendances ne seront pas installées et votre module malheureusement inutilisable.

"dependencies": {
    "request": "~2.81.0"
  },

Avec à gauche le nom du module en question et à droite la version du module qui doit être utilisée.

Créer un module Node.js

Que serait un module sans code ni fonctionnalité ? Pas grand-chose effectivement ! Comme nous l’avons défini dans le package.json, le point d’entrée de notre module correspond au fichier index.js, qui n’existe pas encore. La première étape est donc de le créer !

Une fois le fichier dans le répertoire de notre module, à côté du fichier de configuration, il nous faut maintenant écrire un peu de code, voilà le code que je vous propose.

'use strict';

module.exports = function(number) {
    return number * 2;
};

Il y a ici deux éléments à prendre en compte, le use strict est simplement INDISPENSABLE, sans, votre module ne fonctionnera pas. Ne l’oubliez donc surtout pas ! Et le module.exports est lui aussi important et permet, comme son nom l’indique, d’exporter le module pour rendre accessible la fonction quand une personne de l’extérieur voudra l’utiliser.

J’avoue ne pas être fan de l’utilisation d’une fonction, je ne peux que vous conseiller une classe, maintenant disponible avec la norme ES6 de JavaScript ! Comment ça marche ? Et bien de la même façon.

"use strict";

class API_SG
{
    constructor(number)
    {
        this.var = number;
    }
}
module.exports = API_SG;

Je ne vais pas m’étendre plus longuement sur le code en lui-même. Souvenez-vous simplement que pour exporter une fonction ou une classe, pour la rendre accessible dans votre module, rien de plus simple: il suffit d’utiliser module.exports.

Ajout d’une description sur votre page npm

Avant de mettre en ligne notre super module, il serait bien de faire une description de notre projet pour la page npm, avec de préférence quelques explications sur son fonctionnement par exemple. Et bien bonne nouvelle c’est très simple, cela fonctionne comme pour GitHub ! C’est-à-dire un fichier README.md.

Tout est dit, il vous suffit de créer à côté de package.json un nouveau fichier du nom de README.md et d’y mettre à l’intérieur les différentes informations que vous souhaitez partager. Le tout au format Markdown. Pour ceux qui ne sont pas familiarisés avec ce langage, vous trouverez le nécessaire sur le site officiel.

Lors de la mise en ligne, le fichier markdown sera automatiquement empaqueté dans notre module et envoyer sur le site npm pour remplir notre page !

Mise en ligne

Nous y sommes, la dernière étape, la plus importante sûrement : le moment est venu de rendre notre module accessible à tout le monde ! Et bonne nouvelle ça va être très simple. Une seule commande (à effectuer dans le répertoire de votre module, à côté du package.json) est suffisante et bonne nouvelle, ce sera la même si vous souhaitez mettre à jour votre module dans le futur.

npm publish --access=public

Et voilà ! Si vous avez une erreur cela peut être dû au fait que le nom de votre extension est déjà utilisé. Pour corriger le problème, changer-le dans le fichier de configuration du module. Pourquoi donc —access=public ? Simplement pour rendre notre module public, sans cette précision celui-ci sera privée et mauvaise nouvelle, il vous faudra payer dans ce cas.

Votre module est donc maintenant en ligne sur le site de npm ! Vous devriez pouvoir le retrouver depuis votre compte sur le site internet, dans la liste des modules en ligne. Maintenant un utilisateur n’aura plus qu’à faire un npm i nomDuModule  et le tour sera joué !

Si vous souhaitez utiliser votre module dans un autre projet, il suffira de faire comme d’habitude. Dans le code JavaScript de votre projet principal, là où vous avez installé le module il suffit de l’importer de cette façon import NomModule from 'nomDuModule';