Bun fornisce una strategia di installazione pacchetti alternativa chiamata installazioni isolate che crea un isolamento rigoroso delle dipendenze simile all'approccio di pnpm. Questa modalità previene le dipendenze fantasma e garantisce build riproducibili e deterministiche.

Questa è la strategia di installazione predefinita per i progetti workspace/monorepo nuovi (con configVersion = 1 nel lockfile). I progetti esistenti continuano a usare installazioni hoisted a meno che non siano configurati esplicitamente.

Cosa sono le installazioni isolate?

Le installazioni isolate creano una struttura di dipendenze non-hoisted dove i pacchetti possono accedere solo alle loro dipendenze dichiarate esplicitamente. Questo differisce dalla strategia di installazione tradizionale "hoisted" usata da npm e Yarn, dove le dipendenze vengono appiattite in una directory node_modules condivisa.

Benefici chiave

• Previene le dipendenze fantasma — I pacchetti non possono importare accidentalmente dipendenze che non hanno dichiarato
• Risoluzione deterministica — Lo stesso albero delle dipendenze indipendentemente da cos'altro è installato
• Migliore per monorepo — L'isolamento dello spazio di lavoro previene la contaminazione incrociata tra pacchetti
• Build riproducibili — Comportamento di risoluzione più prevedibile tra ambienti

Usare le installazioni isolate

Riga di comando

Usa il flag --linker per specificare la strategia di installazione:

# Usa installazioni isolate
bun install --linker isolated

# Usa installazioni hoisted tradizionali
bun install --linker hoisted

File di configurazione

Imposta la strategia di linker predefinita nel tuo bunfig.toml o globalmente in $HOME/.bunfig.toml:

[install]
linker = "isolated"

Comportamento predefinito

La strategia di linker predefinita dipende dal configVersion del lockfile del tuo progetto:

configVersion	Usa workspaces?	Linker Predefinito
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

Nuovi progetti: Predefinito a configVersion = 1. Nei workspaces, v1 usa il linker isolated per impostazione predefinita; altrimenti usa il linker hoisted.

Progetti Bun esistenti (creati pre-v1.3.2): Se il tuo lockfile esistente non ha ancora una versione, Bun imposta configVersion = 0 quando esegui bun install, preservando il precedente linker hoisted predefinito.

Migrazioni da altri package manager:

• Da pnpm: configVersion = 1 (usando installazioni isolate nei workspaces)
• Da npm o yarn: configVersion = 0 (usando installazioni hoisted)

Puoi sovrascrivere il comportamento predefinito specificando esplicitamente il flag --linker o impostandolo nel tuo file di configurazione.

Come funzionano le installazioni isolate

Struttura delle directory

Invece di hoistare le dipendenze, le installazioni isolate creano una struttura a due livelli:

node_modules/
├── .bun/                          # Archivio pacchetti centrale
│   ├── package@1.0.0/             # Installazioni pacchetti versionate
│   │   └── node_modules/
│   │       └── package/           # File effettivi del pacchetto
│   ├── @scope+package@2.1.0/      # Pacchetti con scope (+ sostituisce /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # Symlink

Algoritmo di risoluzione

1. Archivio centrale — Tutti i pacchetti sono installati in directory node_modules/.bun/package@version/
2. Symlink — node_modules di livello superiore contiene symlink che puntano all'archivio centrale
3. Risoluzione peer — Dipendenze peer complesse creano nomi di directory specializzati
4. Deduplicazione — Pacchetti con ID pacchetto identici e insiemi di dipendenze peer sono condivisi

Gestione workspace

Nei monorepo, le dipendenze workspace sono gestite in modo speciale:

• Pacchetti workspace — Collegati tramite symlink direttamente alle loro directory sorgente, non all'archivio
• Dipendenze workspace — Possono accedere ad altri pacchetti workspace nel monorepo
• Dipendenze esterne — Installate nell'archivio isolato con isolamento appropriato

Confronto con installazioni hoisted

Aspetto	Hoisted (npm/Yarn)	Isolated (simile a pnpm)
Accesso dipendenze	I pacchetti possono accedere a qualsiasi dipendenza hoisted	I pacchetti vedono solo dipendenze dichiarate
Dipendenze fantasma	❌ Possibili	✅ Prevenute
Uso disco	✅ Inferiore (installazioni condivise)	✅ Simile (usa symlink)
Determinismo	❌ Meno deterministico	✅ Più deterministico
Compatibilità Node.js	✅ Comportamento standard	✅ Compatibile tramite symlink
Ideale per	Progetti singoli, codice legacy	Monorepo, gestione rigorosa dipendenze

Funzionalità avanzate

Gestione dipendenze peer

Le installazioni isolate gestiscono le dipendenze peer attraverso una risoluzione sofisticata:

# Pacchetto con dipendenze peer crea percorsi specializzati
node_modules/.bun/package@1.0.0_react@18.2.0/

Il nome della directory codifica sia la versione del pacchetto che le versioni delle dipendenze peer, garantendo che ogni combinazione unica ottenga la propria installazione.

Strategie backend

Bun usa diverse strategie di operazione file per le prestazioni:

• Clonefile (macOS) — Cloni filesystem copy-on-write per massima efficienza
• Hardlink (Linux/Windows) — Hardlink per risparmiare spazio su disco
• Copyfile (fallback) — Copie complete di file quando altri metodi non sono disponibili

Debug installazioni isolate

Abilita il logging verbose per comprendere il processo di installazione:

bun install --linker isolated --verbose

Questo mostra:

• Creazione voci archivio
• Operazioni symlink
• Risoluzione dipendenze peer
• Decisioni di deduplicazione

Risoluzione problemi

Problemi di compatibilità

Alcuni pacchetti potrebbero non funzionare correttamente con installazioni isolate a causa di:

• Percorsi hardcoded — Pacchetti che assumono una struttura node_modules piatta
• Import dinamici — Import runtime che non seguono la risoluzione Node.js
• Strumenti build — Strumenti che scansionano direttamente node_modules

Se incontri problemi, puoi:

1. Passare alla modalità hoisted per progetti specifici:

   bun install --linker hoisted

2. Segnalare problemi di compatibilità per aiutare a migliorare il supporto alle installazioni isolate

Considerazioni sulle prestazioni

• Tempo installazione — Potrebbe essere leggermente più lento a causa delle operazioni symlink
• Uso disco — Simile a hoisted (usa symlink, non copie di file)
• Uso memoria — Più alto durante l'installazione a causa della risoluzione complessa delle peer

Guida alla migrazione

Da npm/Yarn

# Rimuovi node_modules e lockfile esistenti
rm -rf node_modules package-lock.json yarn.lock

# Installa con linker isolated
bun install --linker isolated

Da pnpm

Le installazioni isolate sono concettualmente simili a pnpm, quindi la migrazione dovrebbe essere semplice:

# Rimuovi file pnpm
rm -rf node_modules pnpm-lock.yaml

# Installa con il linker isolated di Bun
bun install --linker isolated

La differenza principale è che Bun usa symlink in node_modules mentre pnpm usa un archivio globale con symlink.

Quando usare installazioni isolate

Usa installazioni isolate quando:

• Lavori in monorepo con più pacchetti
• È richiesta una gestione rigorosa delle dipendenze
• È importante prevenire dipendenze fantasma
• Costruisci librerie che necessitano dipendenze deterministiche

Usa installazioni hoisted quando:

• Lavori con codice legacy che assume node_modules piatto
• È richiesta compatibilità con strumenti build esistenti
• Lavori in ambienti dove i symlink non sono ben supportati
• Preferisci il comportamento npm tradizionale più semplice

Documentazione correlata

• Package manager > Workspaces — Gestione workspace monorepo
• Package manager > Lockfile — Comprendere il formato lockfile di Bun
• CLI > install — Riferimento completo comando bun install