npm pnpm — Cheat Sheet

Tag: npm, pnpm, node, package-manager, monorepo

Livello: intermedio

TL;DR: pnpm è un'alternativa a npm estremamente veloce che usa uno store globale e hard link per risparmiare spazio su disco e isolare rigidamente le dipendenze, prevenendo bug legati ai pacchetti fantasma.

Concetti chiave

npm duplica l'installazione dei pacchetti per ogni progetto, consumando enormi quantità di spazio su disco.

pnpm memorizza ogni versione di un pacchetto una sola volta in uno store globale sul sistema.

In pnpm, la cartella node_modules utilizza symlink e hard link per puntare ai file dello store globale.

npm adotta una struttura piatta del node_modules, permettendo al codice di accedere a librerie non dichiarate (phantom dependencies).

pnpm crea un albero di dipendenze annidato e rigoroso: si può importare solo ciò che è dichiarato nel package.json.

pnpm offre un supporto nativo e avanzato per i monorepo tramite la configurazione pnpm-workspace.yaml.

Le performance di pnpm sono drasticamente superiori a npm in risoluzione e installazione.

Domande tipiche e risposte pronte

Q: Qual è il vantaggio principale nel passare da npm a pnpm?R: Risparmiamo tantissimo spazio su disco, abbattiamo i tempi di installazione in CI e blindiamo l'albero delle dipendenze per evitare crash inaspettati.

Q: Cosa sono le phantom dependencies?R: Sono sub-dipendenze che npm eleva alla radice del progetto. Se le importo senza dichiararle nel package.json e la libreria genitrice cambia, l'app si rompe.

Q: Qual è l'equivalente del comando npx in pnpm?R: Si utilizza pnpm dlx per scaricare ed eseguire un binario usa e getta in un ambiente isolato.

Q: Perché il progetto si rompe se lo migro a pnpm?R: Il motivo più comune è che l'applicazione faceva affidamento su dipendenze fantasma che pnpm nasconde correttamente. Vanno dichiarate esplicitamente.

Insidie e errori comuni

Modificare i file dentro node_modules generato da pnpm altera il file originale nello store globale, corrompendo l'installazione per tutti i progetti sulla macchina.

In ambienti CI/CD bisogna configurare il caching per puntare allo store globale di pnpm, non banalmente alla cartella node_modules locale.

Costruire immagini Docker richiede passaggi specifici: solitamente si monta lo store globale e si usa pnpm fetch per ottimizzare i layer.

Alcune librerie e vecchi framework che si aspettano la struttura piatta di npm possono presentare errori di risoluzione con i symlink di pnpm.

Snippet e comandi

# Inizializzare un progetto (crea package.json)
pnpm init

# Installare le dipendenze esistenti
pnpm install

# Aggiungere una dipendenza standard
pnpm add react

# Aggiungere una dipendenza per lo sviluppo
pnpm add -D typescript

# Rimuovere un pacchetto
pnpm remove lodash

# Eseguire un comando remoto senza installarlo
pnpm dlx create-next-app@latest

# Eseguire uno script del package.json
pnpm run build
pnpm build # scorciatoia supportata