NPM e il cuore del progetto: package.json

Dopo aver capito come funziona l’asincronia, è il momento di imparare a dare una struttura professionale ai nostri progetti. Benvenuti nel mondo di NPM (Node Package Manager).

NPM unisce due cose: uno strumento da terminale e un enorme registro online di librerie. In pratica, è ciò che ti permette di installare dipendenze, aggiornare versioni e automatizzare comandi.

---

Cos’è un gestore di pacchetti

Un gestore di pacchetti automatizza quattro attività fondamentali:

• installazione delle librerie
• aggiornamento delle versioni
• configurazione del progetto
• distribuzione del software

In altri ecosistemi trovi strumenti simili: in Java, ad esempio, si usa Maven. In Node.js, lo standard è NPM.

---

Inizializzazione e Gestione delle Dipendenze

Ogni progetto Node.js inizia con un file chiamato package.json. Per crearlo, si utilizza il comando di inizializzazione npm init:

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: (node)
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
type: (commonjs) module
About to write to /home/elia97/node/package.json:

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


Is this OK? (yes)

Se vuoi saltare le domande e usare i valori predefiniti, puoi usare la modalità rapida npm init -y.

Creare l’Entry Point

Dopo aver inizializzato il progetto, il passo successivo è creare il file principale. Per convenzione si chiama index.js:

# Linux/macOS
touch index.js

# Windows (PowerShell)
New-Item index.js -ItemType File

Aggiungi un semplice messaggio per testare il setup:

console.log("Hello from Node.js! 🚀")

Configurare gli Script NPM

Apri il package.json e modifica la sezione scripts:

"scripts": {
  "start": "node index.js",
  "dev": "node --watch index.js"
}

Ora puoi avviare il tuo progetto con:

npm start        # Esegue una volta
npm run dev      # Esegue con auto-reload

---

Varianti di Installazione e Flag

Quando installi una libreria, NPM la salva nella cartella node_modules/ e aggiorna il package.json. Esistono diverse modalità:

• —save: aggiunge a dependencies (default). Sono i pacchetti necessari per far girare l’app in produzione.
• —save-dev: aggiunge a devDependencies. Sono strumenti utili solo durante lo sviluppo (es. test runner).
• —save-optional: inserisce in optionalDependencies.
• —no-save: installa senza modificare il package.json.
• -g: installazione globale per usare il pacchetto come comando CLI ovunque nel sistema.

Aggiornamento e Versionamento (SemVer)

NPM gestisce le versioni seguendo il Semantic Versioning (MAJOR.MINOR.PATCH). Puoi aggiornare i pacchetti con npm update <nome> o rimuoverli con npm uninstall <nome>.

Nel package.json troverai simboli come:

• ^1.2.3: accetta aggiornamenti compatibili (Minor e Patch).
• ~1.2.3: accetta solo correzioni di bug (Patch).

---

La Struttura: node_modules e Lockfile

Un progetto Node.js si poggia su due pilastri fondamentali che garantiscono ordine e riproducibilità:

1. node_modules: È la cartella che contiene tutto il codice delle librerie installate. Poiché può diventare estremamente pesante, non va mai inclusa nel sistema di versionamento (Git).
2. package-lock.json: Viene generato automaticamente e registra le versioni esatte di ogni singola dipendenza (comprese le dipendenze delle dipendenze). Garantisce che ogni sviluppatore del team lavori esattamente con lo stesso ambiente.

---

Anatomia del package.json

Il package.json è la carta d’identità del tuo progetto. Ecco gli attributi fondamentali che devi conoscere:

• name: il nome del pacchetto (minuscolo, senza spazi o caratteri speciali).
• version: la versione corrente del progetto.
• description: una breve spiegazione del modulo.
• author: il creatore del progetto (può essere una stringa o un oggetto).
• contributors: lista di persone che collaborano al progetto.
• homepage: l’indirizzo URL del sito ufficiale del progetto.
• repository: indica dove risiede il codice sorgente (es. GitHub).
• license: il tipo di licenza (es. MIT, ISC).
• main: il file di ingresso dell’applicazione (solitamente index.js).
• dependencies: le librerie fondamentali per l’esecuzione in produzione.
• devDependencies: le librerie necessarie solo per lo sviluppo.
• scripts: comandi personalizzati per automatizzare i task.
• keywords: parole chiave per aiutare a trovare il pacchetto nel registro NPM.

---

Gli Script: Automazione al Servizio dei Developer

La sezione scripts è uno degli strumenti più flessibili di NPM. Ti permette di creare alias per comandi complessi, facilitando la vita a chiunque collabori al progetto.

"scripts": {
  "start": "node index.js",
  "dev": "node index.js --watch",
  "test": "jest"
}

Puoi richiamare questi comandi con npm run <nome-script> (o semplicemente npm start per lo script standard).

---