Guide all'installazione

Comandi npm: guida alla gestione dei pacchetti

Una guida passo passo, con comandi di esempio, per installare e aggiornare i pacchetti con npm, eseguire gli script e gestire package.json.

Aurora YazılımRedazione 6 min di lettura
npm Commands: A Package Management Guide
Quali sono i comandi npm più usati?

La maggior parte del lavoro quotidiano si svolge con pochi comandi npm: npm init avvia il progetto, npm install installa le dipendenze, npm install nome-pacchetto aggiunge un nuovo pacchetto, npm run nome-script esegue uno script di package.json e npm update aggiorna i pacchetti. npx esegue uno strumento una sola volta senza installarlo, e npm ci esegue un'installazione pulita che segue esattamente il lock file.

Cos'è npm e a cosa serve?

npm (Node Package Manager) è il gestore di pacchetti del mondo JavaScript. Permette di aggiungere al progetto librerie scritte da altri, di tenere traccia delle loro versioni e di eseguire da un unico punto i comandi legati al progetto.

npm viene fornito con Node.js; non serve installarlo separatamente. Se non avete ancora installato Node.js, seguite prima la nostra guida all'installazione di Node.js, poi provate i comandi di questo articolo nel vostro terminale.

npm ha tre componenti: lo strumento a riga di comando sul vostro computer, il registry in cui sono ospitati i pacchetti e il file package.json al centro di ogni progetto. Quasi ogni comando legge o aggiorna questo file.

Cos'è package.json?

package.json è la carta d'identità del progetto: qui sono scritti il nome, la versione, le dipendenze e gli script eseguibili. In un nuovo progetto si crea questo file con npm init; l'opzione -y salta tutte le domande usando le risposte predefinite.

  • dependencies: i pacchetti di cui l'applicazione ha bisogno durante l'esecuzione.
  • devDependencies: gli strumenti necessari solo durante lo sviluppo e la build (compilatore, strumento di test, formattatore).
  • scripts: comandi brevi eseguiti con npm run.
  • package-lock.json: registra la versione esatta di ogni pacchetto installato; ricordate di aggiungere questo file a Git.
bashAvviare un nuovo progetto
mkdir ilk-proje cd ilk-proje npm init -y
jsonEsempio di package.json
{ "name": "ilk-proje", "version": "1.0.0", "scripts": { "dev": "vite", "build": "vite build", "test": "node --test" }, "dependencies": { "axios": "^1.7.0" }, "devDependencies": { "vite": "^6.0.0" } }

Installare pacchetti con npm install

npm install è il comando più usato e svolge due compiti diversi. Da solo installa nella cartella node_modules tutte le dipendenze di package.json; con il nome di un pacchetto installa quel pacchetto e lo aggiunge a package.json. La forma breve è npm i.

bashComandi di installazione
# Install all dependencies in the project npm install # Yeni paket ekle (dependencies) npm install axios # Add a development tool (devDependencies) npm install -D prettier # Install a specific version npm install lodash@4 # Global install (for command line tools) npm install -g serve # Remove the package npm uninstall axios

Globale o locale?

Installate i pacchetti in locale ogni volta che è possibile, così il progetto funziona con le stesse versioni su un altro computer. Riservate le installazioni globali agli strumenti a riga di comando che userete ovunque; per gli strumenti occasionali basta npx.

Quando usare npm ci?

npm ci elimina la cartella node_modules, installa le versioni esatte indicate in package-lock.json e non modifica il lock file. È ideale per il deploy su un server, per le pipeline di integrazione continua e per risolvere i problemi del tipo «da me funzionava».

Eseguire script con npm run

Il campo scripts di package.json permette di dare nomi brevi a comandi lunghi. In questo modo tutti nel team avviano il server di sviluppo con npm run dev e la build di produzione con npm run build senza conoscere i dettagli dello strumento.

Alcuni nomi, come start e test, sono speciali e funzionano senza digitare run. Per passare parametri aggiuntivi a uno script si usano due trattini.

bashComandi degli script
npm run dev npm run build npm start npm test # List all defined scripts npm run # Pass a parameter to the script npm run build -- --mode staging

Script pre e post

Se aggiungete pre o post davanti al nome di uno script, npm lo esegue automaticamente prima o dopo. Ad esempio, uno script chiamato prebuild può pulire la vecchia cartella di build subito prima di npm run build. Questo schema evita che qualcuno del team dimentichi un passaggio.

Perché gli script trovano gli strumenti locali

Durante l'esecuzione, npm run aggiunge temporaneamente al PATH la cartella node_modules/.bin del progetto. Quindi in uno script basta scrivere vite o prettier; non serve installare lo strumento a livello globale. Se lo stesso strumento non viene trovato digitandolo direttamente nel terminale, il motivo è questo, e la soluzione è usare npx.

Differenze tra sistemi operativi negli script

Comandi come rm -rf non funzionano nella shell predefinita di Windows. Se il vostro team usa sistemi operativi diversi, nei vostri script preferite strumenti Node.js multipiattaforma o brevi script Node.js; così lo stesso package.json dà lo stesso risultato su ogni macchina.

Aggiornare e controllare i pacchetti

I pacchetti vengono aggiornati regolarmente: le falle di sicurezza vengono chiuse e arrivano nuove funzionalità. Prima di aggiornare, eseguite il comando npm outdated per vedere cosa è obsoleto.

Il simbolo ^ in package.json consente le versioni minor e patch (1.7.0 → 1.9.2), mentre il simbolo ~ consente solo le versioni patch (1.7.0 → 1.7.5). npm update aggiorna entro questi limiti; per passare a una nuova versione major bisogna reinstallare il pacchetto con @latest, e di solito servono modifiche al codice.

bashAggiornamenti e sicurezza
# Eskiyen paketleri listele npm outdated # Update within the allowed range npm update # Move to the next major version (use with care) npm install axios@latest # Security audit npm audit npm audit fix # View installed packages npm ls --depth=0 npm ls -g --depth=0 # The latest published version of a package npm view axios version

Cos'è npx e quando usarlo?

npx è un esecutore di pacchetti fornito con npm. Permette di eseguire uno strumento una sola volta senza installarlo a livello globale; lo strumento viene cercato prima nella cartella node_modules del progetto e, se non c'è, viene scaricato temporaneamente.

Creare un modello di progetto è l'uso più comune di npx. Ad esempio, il comando npm create serve per avviare un nuovo progetto React con Vite; i dettagli sono nel nostro articolo configurare React con Vite.

bashEsempi di npx
# Serve the folder on a local server npx serve . # Run the formatter installed in the project npx prettier --write . # New project from a template (does the same job as npm create, npx create-...) npm create vite@latest

npm, yarn e pnpm a confronto

npm non è l'unica opzione; anche yarn e pnpm installano pacchetti dallo stesso registry. Poiché tutti e tre usano package.json, la struttura del progetto non cambia; le differenze emergono nella velocità di installazione, nell'uso del disco e nel lock file.

  • Usate un solo gestore di pacchetti in un progetto; avere due lock file contemporaneamente porta a confusione sulle versioni.
  • Se vi unite a un progetto esistente, guardate il lock file nella cartella e scegliete lo stesso strumento.
  • Se state appena iniziando, partire da npm è la strada con meno attrito.
StrumentoLock filePunto di forza
npmpackage-lock.jsonIncluso in Node.js, nessuna installazione aggiuntiva
yarnyarn.lockWorkspace e diverse modalità di installazione
pnpmpnpm-lock.yamlRisparmia spazio su disco conservando i pacchetti in uno store condiviso

Errori comuni e soluzioni

La maggior parte degli errori di npm deriva da una cache danneggiata, da una versione di Node.js incompatibile o da dipendenze in conflitto. Leggete prima le prime righe del messaggio di errore; di solito la soluzione è spiegata lì.

  • Errore ERESOLVE / peer dependency: uno dei pacchetti si aspetta una versione diversa di un altro pacchetto. Aggiornate i pacchetti a versioni compatibili; come soluzione temporanea si può usare npm install --legacy-peer-deps.
  • node_modules danneggiata: eliminate la cartella node_modules ed eseguite npm install o npm ci. Eliminare il lock file è l'ultima risorsa.
  • Problema di cache: npm cache verify controlla la cache; se necessario, svuotatela con npm cache clean --force.
  • Errore di permessi EACCES: non usate sudo per le installazioni globali; reinstallate Node.js con nvm.
  • Avviso Engine: se un pacchetto richiede una versione più recente di Node.js, passate alla versione LTS con nvm.

Usare bene npm nei vostri progetti

Troppi pacchetti aumentano sia il rischio per la sicurezza sia la quantità di JavaScript che una pagina invia al browser. Chiedersi «posso risolverlo con poche righe di codice?» prima di ogni nuova dipendenza è l'ottimizzazione più economica per la velocità della pagina. Trattiamo regolarmente questo tema nel nostro servizio di ottimizzazione di velocità e prestazioni.

Non aggiungete mai la cartella node_modules a Git; inseritela in .gitignore e condividete solo package.json e il lock file. Abbiamo spiegato passo dopo passo come caricare un progetto su un repository remoto nella nostra guida caricare un progetto su GitHub.

Se state pianificando il web design per la vostra azienda, oppure un progetto di integrazione che collega sistemi di pagamento, spedizione e contabilità, impostare correttamente la gestione delle dipendenze fin dall'inizio riduce i costi di manutenzione nel lungo periodo. Per altri contenuti su Node.js, consultate la pagina del tag nodejs.

Domande frequenti

01Posso eliminare il file package-lock.json?

Si consiglia di non farlo. Questo file garantisce che tutti nel team e il server installino le stesse versioni; se lo eliminate, alla prossima installazione potrebbero arrivare sotto-versioni diverse.

02Qual è la differenza tra npm install e npm ci?

npm install aggiorna il lock file quando serve e installa sopra l'esistente node_modules. npm ci ricostruisce la cartella da zero e restituisce un errore se il lock file e package.json non corrispondono; per questo è più affidabile per il deploy.

03Perché il comando di un pacchetto installato globalmente non funziona?

La cartella dei pacchetti globali potrebbe non essere nel PATH, oppure potreste aver cambiato versione di Node.js. Individuate la cartella con il comando npm prefix -g e aggiungetela al PATH; se usate nvm, reinstallate il pacchetto nella nuova versione.

Imparare i comandi npm apre la porta allo sviluppo web moderno: si installa con npm install, si esegue con npm run e si distribuisce in sicurezza con npm ci. Se volete trasformare queste basi in un sistema costruito per la vostra azienda, scoprite le soluzioni software su misura di Aurora Yazılım oppure contattateci per parlare del vostro progetto.