NPM: cos'è, come utilizzarlo e come installare un modulo a livello locale o globale

di Giulio di Bari :: 01 ottobre 2020

In un articolo precedente ci siamo occupati dell'installazione di Node.js, un framework utilizzato per scrivere applicazioni in Javascript lato server.

Node.js vive grazie alle migliaia di librerie (moduli) javascript scaricabili grazie allo strumento NPM, il Node Package Manager, che, dopo l'installazione di Node.js, abbiamo a nostra disposizione.

NPM consente di scaricare ed installare i moduli con un semplice comando.

Cercare un modulo

Tutti i moduli sono pubblicati nel sito web www.npmjs.com

Su questo sito sono disponibili migliaia di moduli ed è possibile cercare il modulo di cui abbiamo bisogno per il nostro progetto dalla barra di ricerca del sito.

Ad esempio, abbiamo bisogno di intallare la libreria GULP, noto toolkit JavaScript che ci aiuta ad automatizzare e semplificare il nostro sviluppo di un sito web lato frontend, come ad esempio nella minificazione dei file css e js e nella ottimizzazione delle immagini.

Indicherò nella barra di ricerca "gulp" e verranno visualizzate tutte le librerie disponibili.

L'alternativa al sito è lo strumento da riga di comando di NPM.

Apriamo il nostro terminale e digitiamo

# npm search gulp

Otteniamo la lista di librerie disponibili.

Tra queste ci interessa gulp-cli, cioè l'interfaccia da riga di comando di gulp.

Installazione di un modulo a livello locale

Con una installazione locale, il pacchetto verrà installato, e potrà essere utilizzato, solo nella directory di lavoro corrente.

Posizioniamoci della cartella del nostro progetto, ad esempio la cartella "miosito"

# cd /var/www/html/miosito

Ogni progetto necessita di un file chiamato "package.json" che contiene varie informazioni tra cui il nome del progetto, la sua versione e le sue dipendenze.

Come prima cosa, per creare questo file, inizializziamo il progetto digitando

# npm init

II risultato sarà una interazione in cui dobbiamo fornire alcune informazioni relative al progetto, ad esempio il nome del progetto (se non indichiamo nulla il nome sarà il nome della directory che lo contiene). Lasciamo tutte le impostazioni di default e alla fine digitiamo "yes"

[root@vas100 miosito]# npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (miosito)
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to /var/www/miosito/package.json:

{
  "name": "miosito",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}


Is this OK? (yes) yes

Il file "package.json" è stato creato. Questo il suo contenuto

{
  "name": "miosito",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Adesso, sempre nella cartella "miosito", possiamo procedere ad installare il pacchetto scelto

# npm install nomepacchetto

dove al posto di "nomepacchetto" indichiamo il pacchetto scelto, nel nostro esempio "gulp-cli"

# npm install gulp-cli

L'output sarà

.................
+ gulp-cli@2.3.0
added 255 packages from 166 contributors and audited 255 packages in 3.9s

13 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Nella cartella "miosito" è stata creata una nuova cartella chiamata "node_modules" dove è stato scaricato il modulo e le sue dipendipenze.

Inoltre è stato modificato il file "package.json", apriamolo e vediamo che è stata aggiunta la dipendenza "gulp-cli" appena installata, quindi viene indicato espressamente che questo progetto necessita del pacchetto "gulp-cli" nella versione 2.3.0, per funzionare.

{
  "name": "miosito",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "gulp-cli": "^2.3.0"
  }
}

Bene, il pacchetto è installato e pronto all'uso (se ti interessa, a breve pubblicherò un articolo dedicato a GULP).

Installazione di un modulo a livello globale

Se avessi bisogno di utilizzare il pacchetto installato (GULP) in più progetti, e non solo in "miosito", è preferibile installare il modulo non a livello locale, bensì globale, aggiungendo l'opzione "-g" al comando di installazione

# npm install gulp-cli -g

Così facendo il modulo sarà utilizzabile in qualunque progetto / cartella del nostro server.

Aggiornamento dei moduli

Per aggiornare i moduli installati è sufficiente digitare

# npm update

NPM verificherà se ci sono nuove versioni dei moduli, aggiornerà quelli installati sulla tua macchina (facendo attenzione a rispettare la compatibilità) e cancellerà le vecchie versioni.

Numero di versione dei moduli e delle dipendenze

Nel file "package.json" abbiamo visto come sia indicato come versione del progetto la "1.0.0" e tra le dipendenze il modulo "gulp-cli" la cui versione è la "^2.3.0"

Vediamo come leggere questo numero di versione. Divisi dal punto abbiamo

Un numero di versione maggiore
Si inizia con la versione "1". Questo numero cambia solo quando l’applicazione ha avuto una grossa modifica. Nel nostro esempio siamo giunti alla versione maggiore "2"
Si potrebbe anche partire dalla versione "0" quando il progetto non è ancora in produzione.
Un numero di versione minore
Questo numero cambia ogni volta che l’applicazione subisce piccole modifiche.
Nel nostro esempio siamo giunti alla versione minore "3"
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.
Nel nostro esempio il numero di patch "0" cioè non sono state apportate modifiche per bug o errori.

Se guardiamo bene nel file "package.json", la versione della dipendenza è preceduta da un tilde "^", cioè "^2.3.0"

Questo significa che il nostro progetto può funzionare non solo con la versione 2.3.0, ma anche con gli aggiornamenti delle patch cioè con le versioni 2.3.1, 2.3.2, 2.3.3, ecc. ma non quelle superiori come ad esempio la 2.4.0.

Per cui se il pacchetto "gulp-cli" viene aggiornato ad esempio alla versione "2.3.2", se scarico gli aggiornamenti con "npm update" verrà scaricato l'aggiornamento.

Se invece non ci fosse stato il tilde, cioè fosse stato indicato semplicemente "2.3.0", il nostro progetto potrà usare solo questa versione del pacchetto "gulp-cli" e se procedo con "npm update" non verrà scaricato l'eventuale aggiornamento del pacchetto "gulp-cli"

Creazione di un modulo

I moduli NPM vengono creati da sviluppatori di tutto il mondo. Chiunque può creare un modulo e pubblicarlo sul server NPM.

Ogni modulo avrà il suo file "package.json" che conterrà il nome del modulo, la sua attuale versione e le eventuali dipendenze.

Se creiamo un modulo, partiamo, secondo quanto abbiamo indicato nel paragrafo precedente, con la versione "0.1.0", per cui il file "package.json" conterrà questa riga

"version": "1.0.0",

Lo sviluppo del modulo comporterà la modifica del numero di versione nel file "package.json"

Se correggo un bug, l’applicazione passerà versione 1.0.1
Se miglioro in modo significativo la mia applicazione, si trasformerà in versione 1.1.1, poi 1.2.1 e così via.
Il giorno in cui deciderò che ha raggiunto un importante punto di svolta ed è ormai matura, andrò a trasformare il progetto nella versione 2.0.0

Creato il nostro primo pacchetto, vediamo come pubblicarlo su NPM

Innanzitutto dobbiamo creare un account su NPM, o direttamente sul sito www.npmjs.com cliccando sul pulsante di registrazione "signup", oppure da riga di comando digitando

# npm adduser

Ti verrà chiesta una username, una password e una email (che verrà resa pubblica)

Indica questi dati et woilà, l'account è creato. Se andiamo sul sito NPM possiamo loggarci, ma non ancora pubblicare.

Riceverai una email all'indirizzo indicato, con un link per confermare l'indirizzo e-mail. Solo a seguito di tale conferma potremmo pubblicare i nostri pacchetti.

Bene, adesso prepariamoci alla pubblichazione del nostro progetto.

Nella directory del progetto, ad esempio la cartella "mioprogetto", deve esserci

un file "package.json" che descrive il modulo, al cui interno abbiamo indicato come "name" del progetto "mioprogetto" (potevamo un nome qualunque)
un file "README.md" (scritto in markdown) che descrive in modo più dettagliato il modulo

Posizioniamoci nella cartella

# cd /var/www/html/mioprogetto

e lanciamo il comando

# npm publish

Tutto qui: il package è adesso presente su NPM

Considerando che questa è solo una prova, cancelliamo il pacchetto inviato, con il comando

# npm unpublish <package-name> -f

E con questo abbiamo ultimato la presentazione di NPM.

Rimandiamo alla documentazione ufficiale per ulteriori approfondimenti.

Approfondimenti

Documentazione ufficiale NPM