Publier ses modules sur #npm pour #node.js

Réaliser ses propres modules pour node.js et les distribuer par le npm n'est pas très compliqué.

Ce post est destiné à exposer la manière de faire un module, le tester et afin le distribuer.

npm

npm est le node packager manager. C'est l'équivalant du cpan et de la commande cpan pour Perl ou encore du système de 'gems' gemmes pour Ruby.
npm est à la fois un dépot et une commande pour gérer ses modules.
lien sur npm

Préparation d'un  module pour npm.

Un module est tout d'abord une archive compressée contenant un fichier de metadonnée :le package.json et les fichiers de votre module.

La première opération à faire est de créer un répertoire de travail pour votre module:
ex : mon_mondule/
Puis en fonction des besoins, des sous-réperoires seront  préparés:

•  tests/ : car vous êtes un développeur consciencieux
•  lib/   : si votre projet prend de l'ampleur
•  examples/ ou exemples/ : car vous êtes vraiment un développeur consciencieux
•  bin/: si vous livrez des exécutables

Enfin un répertoire docs pour votre documentation volumineuse
 npm n'est pas directif dans les règles de nommage des répertoires.

Pour mon module cela donne :
(copie écran)

Dans votre répertoire du module lancer la commande : npm init

Cette commande vous posera une série de question et vos réponses vont servir à confection le fichier package.json

Par la suite les modifications du fichiers se font manuellement

package.json

Exemple de fichier


Le plus important est l'indication du point d'entrée 'main' du module qui sera repris par la commande require.
ici require('ETag')

Versionning avec git et hébergement par github (partie optionnelle)

A partir de la là les bonnes habitudes reviennent : ajouter un fichier .gitignore (le mien est très simple 1 seule ligne : *~ )


Puis lancer la commande 'git init' pour commencer à versionner votre code.

ok vous êtes sur des bons rails.

Pour le reste des  opérations de versionning j'utilise gitk (copie d'écran).

Le source du module sera géré par la forge github. Aussi la création d'un fichier README.MD pour avoir une page d'accueil bien lisible s'impose. L'extension md signifie MarkDown : c'est un langage qui permet d'écrire des pages de documentation plein texte qui seront automatiquement transformées en html.
Le lien suivant permet de se familiariser avec le MarkDown.


Voici le projet installé sur la forge github.

Le packaging

Un fois le module achevé, il suffira de créer une archive compressée (tgz)
L'archive doit contenir un répertoire nommé package qui accueillera votre module.

Avant de publier le module sur npm, un petit test en local s'impose en lançant la commande suivante
npm install nom_module.tgz

Publication du module sur npm

La première chose à faire et valable une bonne fois pour toute est de créer un compte pour npm par la commande suivante:
npm adduser

Afin la publication sera faite par :

npm publish mon_module.tgz
Ca y est votre premier module est sur npm:

Vos utilisateurs peuvent à présent faire npm install mon_module

(avec ou sans l'option -g) 

Les tests du module

Dans le but de faire un livrer un travail de qualité, il est bien de prévoir une batterie de test.
L'idée est d'avoir un point d'entrée pour exécuter des petits programmes de test. C'est le role du programme run.js du répertoire tests.

Le dispositif est complété par un Makefile qui permet d'automatiser le lancement des tests.


Ainsi la ligne du package.json

 "scripts": {

        "test": "node tests/run.js"

    }

permet à vos utilisateurs de tester votre module par
npm test mon_module

En conclusion:  vous n'avez plus d'excuse pour ne pas publier vos modules sur npm.