O Bun fornece uma estratégia alternativa de instalação de pacotes chamada instalações isoladas que cria isolamento estrito de dependências similar à abordagem do pnpm. Este modo previne dependências fantasmas e garante builds reproduzíveis e determinísticos.

Esta é a estratégia de instalação padrão para projetos workspace/monorepo novos (com configVersion = 1 no lockfile). Projetos existentes continuam usando instalações hoisted a menos que configurados explicitamente.

O que são instalações isoladas?

Instalações isoladas criam uma estrutura de dependência não-hoisted onde os pacotes só podem acessar suas dependências explicitamente declaradas. Isso difere da estratégia de instalação tradicional "hoisted" usada por npm e Yarn, onde as dependências são achatadas em um diretório node_modules compartilhado.

Benefícios principais

• Previne dependências fantasmas — Pacotes não podem importar acidentalmente dependências que não declararam
• Resolução determinística — Mesma árvore de dependências independentemente do que mais está instalado
• Melhor para monorepos — Isolamento de workspace previne contaminação cruzada entre pacotes
• Builds reproduzíveis — Comportamento de resolução mais previsível entre ambientes

Usando instalações isoladas

Linha de comando

Use a flag --linker para especificar a estratégia de instalação:

# Usar instalações isoladas
bun install --linker isolated

# Usar instalações hoisted tradicionais
bun install --linker hoisted

Arquivo de configuração

Defina a estratégia de linker padrão no seu bunfig.toml ou globalmente em $HOME/.bunfig.toml:

[install]
linker = "isolated"

Comportamento padrão

A estratégia de linker padrão depende do configVersion do lockfile do seu projeto:

configVersion	Usando workspaces?	Linker padrão
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

Novos projetos: Padrão para configVersion = 1. Em workspaces, v1 usa o linker isolated por padrão; caso contrário, usa linker hoisted.

Projetos Bun existentes (feitos antes da v1.3.2): Se seu lockfile existente ainda não tiver uma versão, o Bun define configVersion = 0 quando você executa bun install, preservando o padrão anterior de linker hoisted.

Migrações de outros gerenciadores de pacotes:

• Do pnpm: configVersion = 1 (usando instalações isoladas em workspaces)
• Do npm ou yarn: configVersion = 0 (usando instalações hoisted)

Você pode substituir o comportamento padrão especificando explicitamente a flag --linker ou definindo-a no seu arquivo de configuração.

Como funcionam as instalações isoladas

Estrutura de diretório

Em vez de hoisted de dependências, instalações isoladas criam uma estrutura de dois níveis:

node_modules/
├── .bun/                          # Armazenamento central de pacotes
│   ├── package@1.0.0/             # Instalações de pacotes versionados
│   │   └── node_modules/
│   │       └── package/           # Arquivos reais do pacote
│   ├── @scope+package@2.1.0/      # Pacotes com escopo (+ substitui /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # Symlinks

Algoritmo de resolução

1. Armazenamento central — Todos os pacotes são instalados em diretórios node_modules/.bun/package@version/
2. Symlinks — node_modules de nível superior contém symlinks apontando para o armazenamento central
3. Resolução de peer — Dependências peer complexas criam nomes de diretório especializados
4. Deduplicação — Pacotes com IDs de pacote idênticos e conjuntos de dependências peer são compartilhados

Manipulação de workspace

Em monorepos, dependências de workspace são tratadas de forma especial:

• Pacotes do workspace — Linkados por symlink diretamente aos seus diretórios de origem, não ao armazenamento
• Dependências do workspace — Podem acessar outros pacotes do workspace no monorepo
• Dependências externas — Instaladas no armazenamento isolado com isolamento adequado

Comparação com instalações hoisted

Aspecto	Hoisted (npm/Yarn)	Isolated (pnpm-like)
Acesso a dependências	Pacotes podem acessar qualquer dependência hoisted	Pacotes só veem dependências declaradas
Dependências fantasmas	❌ Possível	✅ Prevendido
Uso de disco	✅ Menor (instalações compartilhadas)	✅ Similar (usa symlinks)
Determinismo	❌ Menos determinístico	✅ Mais determinístico
Compatibilidade Node.js	✅ Comportamento padrão	✅ Compatível via symlinks
Melhor para	Projetos únicos, código legado	Monorepos, gerenciamento estrito de dependências

Recursos avançados

Manipulação de dependências peer

Instalações isoladas lidam com dependências peer através de resolução sofisticada:

# Pacote com dependências peer cria caminhos especializados
node_modules/.bun/package@1.0.0_react@18.2.0/

O nome do diretório codifica tanto a versão do pacote quanto suas versões de dependências peer, garantindo que cada combinação única receba sua própria instalação.

Estratégias de backend

O Bun usa diferentes estratégias de operação de arquivo para desempenho:

• Clonefile (macOS) — Clones de sistema de arquivos copy-on-write para máxima eficiência
• Hardlink (Linux/Windows) — Hardlinks para economizar espaço em disco
• Copyfile (fallback) — Cópias completas de arquivo quando outros métodos não estão disponíveis

Depurando instalações isoladas

Habilite log verbose para entender o processo de instalação:

bun install --linker isolated --verbose

Isso mostra:

• Criação de entrada no armazenamento
• Operações de symlink
• Resolução de dependências peer
• Decisões de deduplicação

Solução de problemas

Problemas de compatibilidade

Alguns pacotes podem não funcionar corretamente com instalações isoladas devido a:

• Caminhos codificados — Pacotes que assumem uma estrutura node_modules plana
• Importações dinâmicas — Importações em tempo de execução que não seguem a resolução do Node.js
• Ferramentas de build — Ferramentas que escaneiam node_modules diretamente

Se você encontrar problemas, pode:

1. Mudar para modo hoisted para projetos específicos:

   bun install --linker hoisted

2. Relatar problemas de compatibilidade para ajudar a melhorar o suporte a instalações isoladas

Considerações de desempenho

• Tempo de instalação — Pode ser ligeiramente mais lento devido a operações de symlink
• Uso de disco — Similar ao hoisted (usa symlinks, não cópias de arquivo)
• Uso de memória — Maior durante a instalação devido à resolução complexa de peer

Guia de migração

Do npm/Yarn

# Remover node_modules e lockfiles existentes
rm -rf node_modules package-lock.json yarn.lock

# Instalar com linker isolated
bun install --linker isolated

Do pnpm

Instalações isoladas são conceitualmente similares ao pnpm, então a migração deve ser direta:

# Remover arquivos pnpm
rm -rf node_modules pnpm-lock.yaml

# Instalar com linker isolated do Bun
bun install --linker isolated

A principal diferença é que o Bun usa symlinks em node_modules enquanto o pnpm usa um armazenamento global com symlinks.

Quando usar instalações isoladas

Use instalações isoladas quando:

• Trabalhando em monorepos com múltiplos pacotes
• Gerenciamento estrito de dependências é necessário
• Prevenir dependências fantasmas é importante
• Construindo bibliotecas que precisam de dependências determinísticas

Use instalações hoisted quando:

• Trabalhando com código legado que assume node_modules plano
• Compatibilidade com ferramentas de build existentes é necessária
• Trabalhando em ambientes onde symlinks não são bem suportados
• Você prefere o comportamento npm tradicional mais simples

Documentação relacionada

• Package manager > Workspaces — Gerenciamento de workspace monorepo
• Package manager > Lockfile — Entendendo o formato do lockfile do Bun
• CLI > install — Referência completa do comando bun install