Bun proporciona una estrategia alternativa de instalación de paquetes llamada instalaciones aisladas que crea un aislamiento estricto de dependencias similar al enfoque de pnpm. Este modo previene dependencias fantasma y asegura compilaciones reproducibles y deterministas.

Esta es la estrategia de instalación predeterminada para proyectos de espacio de trabajo/monorepo nuevos (con configVersion = 1 en el lockfile). Los proyectos existentes continúan usando instalaciones hoisted a menos que se configure explícitamente.

¿Qué son las instalaciones aisladas?

Las instalaciones aisladas crean una estructura de dependencias no-hoisted donde los paquetes solo pueden acceder a sus dependencias explícitamente declaradas. Esto difiere de la estrategia de instalación tradicional "hoisted" usada por npm y Yarn, donde las dependencias se aplana en un directorio node_modules compartido.

Beneficios clave

• Previene dependencias fantasma — Los paquetes no pueden importar accidentalmente dependencias que no han declarado
• Resolución determinista — El mismo árbol de dependencias sin importar qué más esté instalado
• Mejor para monorepos — El aislamiento del espacio de trabajo previene la contaminación cruzada entre paquetes
• Compilaciones reproducibles — Comportamiento de resolución más predecible en diferentes entornos

Usar instalaciones aisladas

Línea de comandos

Usa la bandera --linker para especificar la estrategia de instalación:

# Usar instalaciones aisladas
bun install --linker isolated

# Usar instalaciones hoisted tradicionales
bun install --linker hoisted

Archivo de configuración

Establece la estrategia de linker predeterminada en tu bunfig.toml o globalmente en $HOME/.bunfig.toml:

[install]
linker = "isolated"

Comportamiento predeterminado

La estrategia de linker predeterminada depende del configVersion de tu lockfile:

configVersion	¿Usa workspaces?	Linker predeterminado
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

Proyectos nuevos: Por defecto configVersion = 1. En workspaces, v1 usa el linker isolated por defecto; de lo contrario usa linker hoisted.

Proyectos Bun existentes (creados pre-v1.3.2): Si tu lockfile existente aún no tiene versión, Bun establece configVersion = 0 cuando ejecutas bun install, preservando el predeterminado anterior de linker hoisted.

Migraciones desde otros gestores de paquetes:

• Desde pnpm: configVersion = 1 (usando instalaciones aisladas en workspaces)
• Desde npm o yarn: configVersion = 0 (usando instalaciones hoisted)

Puedes sobrescribir el comportamiento predeterminado especificando explícitamente la bandera --linker o estableciéndola en tu archivo de configuración.

Cómo funcionan las instalaciones aisladas

Estructura de directorios

En lugar de hacer hoisted de las dependencias, las instalaciones aisladas crean una estructura de dos niveles:

node_modules/
├── .bun/                          # Almacén central de paquetes
│   ├── package@1.0.0/             # Instalaciones de paquetes versionados
│   │   └── node_modules/
│   │       └── package/           # Archivos reales del paquete
│   ├── @scope+package@2.1.0/      # Paquetes con scope (+ reemplaza /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # Symlinks

Algoritmo de resolución

1. Almacén central — Todos los paquetes se instalan en directorios node_modules/.bun/package@version/
2. Symlinks — El node_modules de nivel superior contiene symlinks apuntando al almacén central
3. Resolución peer — Las dependencias peer complejas crean nombres de directorio especializados
4. Deduplicación — Los paquetes con IDs de paquete idénticos y conjuntos de dependencias peer se comparten

Manejo de espacio de trabajo

En monorepos, las dependencias del espacio de trabajo se manejan especialmente:

• Paquetes del espacio de trabajo — Enlazados directamente a sus directorios de origen, no al almacén
• Dependencias del espacio de trabajo — Pueden acceder a otros paquetes del espacio de trabajo en el monorepo
• Dependencias externas — Instaladas en el almacén aislado con aislamiento apropiado

Comparación con instalaciones hoisted

Aspecto	Hoisted (npm/Yarn)	Isolated (pnpm-like)
Acceso a dependencias	Los paquetes pueden acceder a cualquier dependencia hoisted	Los paquetes solo ven dependencias declaradas
Dependencias fantasma	❌ Posible	✅ Previene
Uso de disco	✅ Menor (instalaciones compartidas)	✅ Similar (usa symlinks)
Determinismo	❌ Menos determinista	✅ Más determinista
Compatibilidad con Node.js	✅ Comportamiento estándar	✅ Compatible vía symlinks
Mejor para	Proyectos únicos, código legacy	Monorepos, gestión estricta de dependencias

Características avanzadas

Manejo de dependencias peer

Las instalaciones aisladas manejan dependencias peer mediante resolución sofisticada:

# El paquete con dependencias peer crea rutas especializadas
node_modules/.bun/package@1.0.0_react@18.2.0/

El nombre del directorio codifica tanto la versión del paquete como sus versiones de dependencias peer, asegurando que cada combinación única obtenga su propia instalación.

Estrategias de backend

Bun usa diferentes estrategias de operación de archivos para rendimiento:

• Clonefile (macOS) — Clones de sistema de archivos copy-on-write para máxima eficiencia
• Hardlink (Linux/Windows) — Hardlinks para ahorrar espacio en disco
• Copyfile (alternativa) — Copias completas de archivos cuando otros métodos no están disponibles

Depurar instalaciones aisladas

Habilita el registro detallado para entender el proceso de instalación:

bun install --linker isolated --verbose

Esto muestra:

• Creación de entradas del almacén
• Operaciones de symlink
• Resolución de dependencias peer
• Decisiones de deduplicación

Solución de problemas

Problemas de compatibilidad

Algunos paquetes pueden no funcionar correctamente con instalaciones aisladas debido a:

• Rutas codificadas — Paquetes que asumen una estructura plana node_modules
• Importaciones dinámicas — Importaciones en runtime que no siguen la resolución de Node.js
• Herramientas de compilación — Herramientas que escanean node_modules directamente

Si encuentras problemas, puedes:

1. Cambiar a modo hoisted para proyectos específicos:

   bun install --linker hoisted

2. Reportar problemas de compatibilidad para ayudar a mejorar el soporte de instalaciones aisladas

Consideraciones de rendimiento

• Tiempo de instalación — Puede ser ligeramente más lento debido a operaciones de symlink
• Uso de disco — Similar a hoisted (usa symlinks, no copias de archivos)
• Uso de memoria — Mayor durante la instalación debido a resolución compleja de peer

Guía de migración

Desde npm/Yarn

# Eliminar node_modules y lockfiles existentes
rm -rf node_modules package-lock.json yarn.lock

# Instalar con linker isolated
bun install --linker isolated

Desde pnpm

Las instalaciones aisladas son conceptualmente similares a pnpm, por lo que la migración debería ser sencilla:

# Eliminar archivos de pnpm
rm -rf node_modules pnpm-lock.yaml

# Instalar con el linker isolated de Bun
bun install --linker isolated

La principal diferencia es que Bun usa symlinks en node_modules mientras que pnpm usa un almacén global con symlinks.

Cuándo usar instalaciones aisladas

Usa instalaciones aisladas cuando:

• Trabajes en monorepos con múltiples paquetes
• Se requiera gestión estricta de dependencias
• Sea importante prevenir dependencias fantasma
• Construyas bibliotecas que necesiten dependencias deterministas

Usa instalaciones hoisted cuando:

• Trabajes con código legacy que asume node_modules plano
• Se requiera compatibilidad con herramientas de compilación existentes
• Trabajes en entornos donde los symlinks no están bien soportados
• Prefieras el comportamiento npm tradicional más simple

Documentación relacionada

• Package manager > Workspaces — Gestión de espacios de trabajo en monorepo
• Package manager > Lockfile — Entendiendo el formato del lockfile de Bun
• CLI > install — Referencia completa del comando bun install