Come pubblicare un modulo nell’NPM
Gestione delle versioni e dipendenze

Tempo di lettura: 4 minuti
Pubblicare un modulo su NPM: Node Package Manager

Stai imparando ad usare Node.js e hai già fatto qualche esperimento ma ora è arrivato il momento di vedere come pubblicare dei moduli nel sito ufficiale dell’NPM! In questo articolo ti spiegherò proprio questo ma prima di parlare di pubblicazione è importante capire come usare le dipendenze e i numeri di versione.

Gestione delle dipendenze: il file package.json

Se il tuo codice ha bisogno di moduli esterni non dovresti avere problemi, puoi installarli uno ad uno come hai già imparato (anche se vedrai che sarà complicato da gestire, soprattutto se si utilizzano più moduli).
C’è però un problema: man mano che questi moduli vengono aggiornati e passano da una versione all’altra, il tuo programma potrebbe diventare incompatibile con le nuove versioni!

Per fortuna, possiamo risolvere tutto questo tramite la definizione delle dipendenze del programma in un semplice file JSON (l’abbiamo già visto nel precedente articolo con l’installazione dei moduli).

È un po’ come la carta d’identità della nostra app.

Crea un file package.json nella stessa cartella dell’app, e scrivi:

{
  "name": "my-app",
  "version": "0.1.0",
  "dependencies": {
    "markdown": "~0.4"
  }
}

Questo file JSON contiene 3 coppie di valori chiave:

  • name: è il nome dell’app. Scegli un nome semplice, evita spazi e accenti.
  • version: è il numero di versione della tua applicazione. È composto da una versione maggiore, una versione minore e una patch. A breve tornerò su questo punto.
  • dependencies: è un array che elenca tutti i nomi dei moduli di cui il tuo modulo ha bisogno per funzionare così come le versioni compatibili.

Questo file può essere molto più complesso, qui ti ho mostrato solo i valori essenziali. Per saperne di più sul funzionamento dei file package.json, ti consiglio di dare un’occhiata alla seguente pagina: https://www.nodejitsu.com/documentation/appendix/package-json/.

Come funzionano i numeri delle versioni

Per gestire correttamente le dipendenze e sapere come aggiornare il numero di versione dell’applicazione, è necessario sapere come funzionano i numeri di versione con Node.js. Per ogni applicazione esiste:

  • Un numero di versione maggiore. In generale si inizia con 0 quando l’applicazione non è considerata completa. Questo numero non cambia spesso, solo quando l’applicazione ha avuto una profonda trasformazione.
  • Un numero di versione minore. Questo numero viene cambiato ogni volta che l’applicazione viene cambiata un po’.
  • Un numero di patch. Questo numero viene cambiato per ogni piccolo bug o errore che è stato corretto. Le caratteristiche dell’app rimangono le stesse tra le patch. Ѐ importante principalmente per le ottimizzazione e le correzioni inevitabili.

La figura seguente mostra quanto ho appena detto:

versioning-applicazione-nodejs-major-minor-patch-number-numero-versione
Numero di versione di un’app Node.js

In questo caso, ho scelto di iniziare la numerazione della mia app alla versione 0.1.0 (avremmo potuto iniziare a 1.0.0.0 ma sarebbe stato pretenzioso).

  • Se correggo un bug, l’applicazione andrà alla versione 0.1.1 e dovrò aggiornare questo numero nel file package.json.
  • Se miglioro in modo significativo la mia applicazione, si trasformerà in versione 0.2.0, poi 0.3.0 e così via.
  • Il giorno in cui deciderò che ha raggiunto un importante punto di svolta ed è ormai matura, sarò in grado di trasformarlo in versione 1.0.0.

Gestione delle versioni nelle dipendendenze

Sei tu che scegli con quali versioni dipendenti la tua app funziona. Se la tua applicazione dipende solo dal modulo markdown v0.3.5, puoi scrivere:

"dependencies": {
  "markdown": "0.3.5" // Versione fissa
}

Se effettui un aggiornamento npm per aggiornare tutti i moduli esterni, il markdown non sarà mai aggiornato (anche se l’applicazione va alla versione 0.3.6).

È possibile mettere un tilde (~) davanti al numero di versione per consentire gli aggiornamenti fino alla versione minore successiva:

"dependencies": {
  "markdown": "~0.3.5" // Vanno bene le versioni 0.3.5, 0.3.6, 0.3.7, ecc. ma non quelle superiori come la 0.4.0
}

Non è necessario includere il numero di patch se non lo si desidera.

In questo caso, i moduli verranno aggiornati anche se l’applicazione cambia versioni minori:

"dependencies": {
  "markdown": "~0.3" // Vanno bene le versioni 0.3.X, 0.4.X, 0.5.X fino alla 1.0.0 non inclusa 
}

Tuttavia, fai attenzione… un modulo può cambiare tra due versioni minori e la tua applicazione potrebbe essere incompatibile.

Consiglio: accetta solo gli aggiornamenti delle patch, è l’opzione più sicura!

Pubblicazione di un modulo nel sito NPM

Con Node.js è possibile creare un’applicazione per le proprie esigenze, ma è anche possibile creare moduli che offrono funzionalità.

Se pensi che il tuo modulo possa essere utile per altre persone, non esitare a condividerlo!

È possibile pubblicarlo su NPM molto facilmente in modo che altre persone possano installarlo da sole.

Ricordati che un modulo non è altro che un’app Node.js che contiene istruzioni di esportazione (export) per condividere le funzioni.

Comincia creando un account su npm:

npm adduser

Una volta fatto ciò, vai nella directory del progetto che vuoi pubblicare e verifica di avere:

  • Un file package.json che descrive il modulo (almeno nome, versione e dipendenze).
  • Un file README.md (scritto in markdown) che presenta il modulo in modo più dettagliato. Sentiti libero di includere qui un mini-tutorial per spiegare come usare il tuo modulo!

Tutto quello che devi fare ora è:

npm publish

Ed ecco che si va, è fatta!

Ora non ti resta che è informare le persone che conosci sul tuo modulo o presentarlo alle mailing list di Node.js!

Conclusioni: Come funzionano i moduli dell’NPM e come pubblicarne dei nuovi

  • I moduli Node.js sono utili per scomporre il codice ed evitare di scrivere tutto in un unico file.
  • Si possono includere i propri moduli con require() come si fa con i moduli ufficiali Node.js.
  • Tutte le funzioni del file modulo richiamabili esternamente devono essere esportate con il comando export.
  • NPM è il gestore dei moduli Node.js. Come apt-get e aptitude in Linux/Debian, permette ai nuovi moduli di essere trovati dalla comunità in un batter d’occhio.
  • I moduli scaricati con NPM sono installati di default localmente nella sottocartella node_modules dell’app.
  • L’estensione -g consente di installare un modulo globalmente per l’intera macchina. È utile solo per pochi moduli specifici.
  • È possibile condividere i propri moduli con il resto della community creando un package.json e un lanciando il comando ‘npm publish’.

 


L’articolo che hai appena letto fa parte di una lunga serie di guide e tutorial tradotte in italiano e distribuite gratuitamente. In particolare questo articolo si basa sui testi inglesi di Mathieu Nebra (Ultra fast applications using Node.js), con licenza CC BY-NC-SA. Questo articolo è sotto la stessa licenza.