Bun fournit une stratégie d'installation de packages alternative appelée installations isolées qui crée une isolation stricte des dépendances similaire à l'approche de pnpm. Ce mode empêche les dépendances fantômes et assure des builds reproductibles et déterministes.

C'est la stratégie d'installation par défaut pour les projets workspace/monorepo nouveaux (avec configVersion = 1 dans le lockfile). Les projets existants continuent d'utiliser les installations hoisted sauf configuration explicite.

Que sont les installations isolées ?

Les installations isolées créent une structure de dépendances non-hoisted où les packages ne peuvent accéder qu'à leurs dépendances explicitement déclarées. Cela diffère de la stratégie d'installation traditionnelle "hoisted" utilisée par npm et Yarn, où les dépendances sont aplaties dans un répertoire node_modules partagé.

Avantages clés

• Empêche les dépendances fantômes — Les packages ne peuvent pas accidentellement importer des dépendances qu'ils n'ont pas déclarées
• Résolution déterministe — Même arborescence de dépendances quel que soit ce qui est installé d'autre
• Meilleur pour les monorepos — L'isolation des workspaces empêche la contamination croisée entre les packages
• Builds reproductibles — Comportement de résolution plus prévisible dans différents environnements

Utilisation des installations isolées

Ligne de commande

Utilisez le drapeau --linker pour spécifier la stratégie d'installation :

# Utiliser les installations isolées
bun install --linker isolated

# Utiliser les installations hoisted traditionnelles
bun install --linker hoisted

Fichier de configuration

Définissez la stratégie de linker par défaut dans votre bunfig.toml ou globalement dans $HOME/.bunfig.toml :

[install]
linker = "isolated"

Comportement par défaut

La stratégie de linker par défaut dépend du configVersion de votre lockfile :

configVersion	Utilise workspaces ?	Linker par défaut
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

Nouveaux projets : Par défaut sur configVersion = 1. Dans les workspaces, v1 utilise le linker isolated par défaut ; sinon il utilise le linker hoisted.

Projets Bun existants (créés avant v1.3.2) : Si votre lockfile existant n'a pas encore de version, Bun définit configVersion = 0 lorsque vous exécutez bun install, préservant le linker hoisted par défaut précédent.

Migrations depuis d'autres gestionnaires de packages :

• Depuis pnpm : configVersion = 1 (utilisant les installations isolées dans les workspaces)
• Depuis npm ou yarn : configVersion = 0 (utilisant les installations hoisted)

Vous pouvez remplacer le comportement par défaut en spécifiant explicitement le drapeau --linker ou en le définissant dans votre fichier de configuration.

Comment fonctionnent les installations isolées

Structure de répertoire

Au lieu de hoister les dépendances, les installations isolées créent une structure à deux niveaux :

node_modules/
├── .bun/                          # Store de packages central
│   ├── package@1.0.0/             # Installations de packages versionnés
│   │   └── node_modules/
│   │       └── package/           # Fichiers réels du package
│   ├── @scope+package@2.1.0/      # Packages scoped (+ remplace /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # Liens symboliques

Algorithme de résolution

1. Store central — Tous les packages sont installés dans les répertoires node_modules/.bun/package@version/
2. Liens symboliques — Le node_modules de niveau supérieur contient des liens symboliques pointant vers le store central
3. Résolution peer — Les dépendances peer complexes créent des noms de répertoires spécialisés
4. Déduplication — Les packages avec des IDs de package identiques et des ensembles de dépendances peer sont partagés

Gestion des workspaces

Dans les monorepos, les dépendances de workspace sont gérées spécialement :

• Packages de workspace — Liés symboliquement directement vers leurs répertoires sources, pas vers le store
• Dépendances de workspace — Peuvent accéder à d'autres packages de workspace dans le monorepo
• Dépendances externes — Installées dans le store isolé avec une isolation appropriée

Comparaison avec les installations hoisted

Aspect	Hoisted (npm/Yarn)	Isolated (style pnpm)
Accès aux dépendances	Les packages peuvent accéder à toute dépendance hoisted	Les packages ne voient que les dépendances déclarées
Dépendances fantômes	❌ Possible	✅ Empêché
Utilisation disque	✅ Plus faible (installations partagées)	✅ Similaire (utilise liens symboliques)
Déterminisme	❌ Moins déterministe	✅ Plus déterministe
Compatibilité Node.js	✅ Comportement standard	✅ Compatible via liens symboliques
Meilleur pour	Projects uniques, code legacy	Monorepos, gestion stricte des dépendances

Fonctionnalités avancées

Gestion des dépendances peer

Les installations isolées gèrent les dépendances peer grâce à une résolution sophistiquée :

# Package avec dépendances peer crée des chemins spécialisés
node_modules/.bun/package@1.0.0_react@18.2.0/

Le nom du répertoire encode à la fois la version du package et ses versions de dépendances peer, garantissant que chaque combinaison unique obtient sa propre installation.

Stratégies backend

Bun utilise différentes stratégies d'opérations de fichiers pour la performance :

• Clonefile (macOS) — Clones de filesystem copy-on-write pour une efficacité maximale
• Hardlink (Linux/Windows) — Liens physiques pour économiser l'espace disque
• Copyfile (repli) — Copies complètes de fichiers lorsque d'autres méthodes ne sont pas disponibles

Débogage des installations isolées

Activez la journalisation verbeuse pour comprendre le processus d'installation :

bun install --linker isolated --verbose

Ceci affiche :

• Création d'entrées de store
• Opérations de liens symboliques
• Résolution de dépendances peer
• Décisions de déduplication

Dépannage

Problèmes de compatibilité

Certains packages peuvent ne pas fonctionner correctement avec les installations isolées en raison de :

• Chemins codés en dur — Packages qui supposent une structure plate node_modules
• Imports dynamiques — Imports runtime qui ne suivent pas la résolution Node.js
• Outils de build — Outils qui scannent node_modules directement

Si vous rencontrez des problèmes, vous pouvez :

1. Passer en mode hoisted pour des projets spécifiques :

   bun install --linker hoisted

2. Signaler les problèmes de compatibilité pour aider à améliorer la prise en charge des installations isolées

Considérations de performance

• Temps d'installation — Peut être légèrement plus lent en raison des opérations de liens symboliques
• Utilisation disque — Similaire à hoisted (utilise des liens symboliques, pas des copies de fichiers)
• Utilisation mémoire — Plus élevée pendant l'installation en raison de la résolution complexe des pairs

Guide de migration

Depuis npm/Yarn

# Supprimer les node_modules et lockfiles existants
rm -rf node_modules package-lock.json yarn.lock

# Installer avec le linker isolated
bun install --linker isolated

Depuis pnpm

Les installations isolées sont conceptuellement similaires à pnpm, donc la migration devrait être simple :

# Supprimer les fichiers pnpm
rm -rf node_modules pnpm-lock.yaml

# Installer avec le linker isolated de Bun
bun install --linker isolated

La principale différence est que Bun utilise des liens symboliques dans node_modules tandis que pnpm utilise un store global avec des liens symboliques.

Quand utiliser les installations isolées

Utilisez les installations isolées quand :

• Vous travaillez dans des monorepos avec plusieurs packages
• Une gestion stricte des dépendances est requise
• Empêcher les dépendances fantômes est important
• Vous construisez des bibliothèques ayant besoin de dépendances déterministes

Utilisez les installations hoisted quand :

• Vous travaillez avec du code legacy qui suppose un node_modules plat
• La compatibilité avec les outils de build existants est requise
• Vous travaillez dans des environnements où les liens symboliques ne sont pas bien pris en charge
• Vous préférez le comportement npm traditionnel plus simple

Documentation connexe

• Package manager > Workspaces — Gestion des workspaces de monorepo
• Package manager > Lockfile — Comprendre le format de lockfile de Bun
• CLI > install — Référence complète de la commande bun install