LEZIONE 10 · Progetto e tooling

package.json e versioni

Prima di iniziare: le parole della lezione

Manifesto e lockfile: Il manifesto dichiara il progetto e gli intervalli di versioni accettati. Il lockfile registra l’albero risolto con versioni precise e informazioni di integrità.
SemVer: Semantic Versioning: schema major.minor.patch. La major segnala modifiche incompatibili dichiarate, la minor funzionalità compatibili, la patch correzioni compatibili.
Script npm: Comando con un nome definito nell’oggetto scripts, avviabile con npm run nome. npm start è la forma breve per lo script start.

package.json è il manifesto del progetto: metadati, script e dipendenze. package-lock.json registra le versioni risolte ed è normalmente da includere nel versionamento.

{
  "name": "laboratorio-node",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {
    "express": "^5.0.0"
  }
}

Attenzione: la versione di Express qui è illustrativa, non un vincolo da incollare ciecamente. È meglio usare npm install express, lasciando che npm scriva la versione effettivamente installata.

^1.2.3: permette aggiornamenti compatibili secondo SemVer all'interno della major 1.
~1.2.3: permette generalmente aggiornamenti patch nella minor 2.
dependencies: necessarie all'esecuzione; devDependencies: strumenti di sviluppo.

Chi fa cosa, e perché

name identifica il pacchetto; version è la versione del tuo progetto, non quella di Node; private: true impedisce la pubblicazione accidentale con npm. type sceglie l’interpretazione dei file .js. main, quando presente, descrive un punto di ingresso del pacchetto per chi lo carica: non sostituisce lo script start.

dependencies raccoglie ciò che serve in esecuzione; devDependencies gli strumenti usati nello sviluppo. Negli script, npm aggiunge al PATH i comandi dei pacchetti locali: per questo nodemon può funzionare senza installazione globale. Conserva nel controllo di versione manifesto e lockfile; normalmente escludi node_modules.

Un altro esempio guidato

{
  "name": "prima-api",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "node server.cjs",
    "dev": "node --watch server.cjs",
    "check": "node --check server.cjs"
  }
}

Come leggerlo e risultato atteso. È un manifesto iniziale valido: salvalo come package.json nella cartella dell’esercizio, crea server.cjs e installa Express per aggiungere la dipendenza. npm run check controlla la sintassi senza avviare il server. JSON richiede doppi apici e non accetta commenti o virgole finali.

Pratica attuale e precisazioni. ^1.2.3 indica versioni da 1.2.3 fino a prima di 2.0.0; ~1.2.3 fino a prima di 1.3.0. Prima della major 1 le regole del caret sono più restrittive: ^0.2.3 non include 0.3.0. Un numero esatto come 1.2.3 non è un intervallo.

Prova tu. Crea saluto.cjs con una stampa e aggiungi "saluto": "node saluto.cjs" agli script; avvialo con npm run saluto.

Torna all’indice ↑