Se nenhum diretório node_modules for encontrado no diretório de trabalho ou acima, o Bun abandonará a resolução de módulos no estilo Node.js em favor do algoritmo de resolução de módulos do Bun.

Na resolução de módulos no estilo Bun, todos os pacotes importados são instalados automaticamente em tempo de execução em um cache de módulos global durante a execução (o mesmo cache usado por bun install).

import { foo } from "foo"; // instala a versão `latest`

foo();

Na primeira vez que você executar este script, o Bun instalará automaticamente "foo" e o armazenará em cache. Na próxima vez que executar o script, usará a versão em cache.

---

Resolução de versão

Para determinar qual versão instalar, o Bun segue o seguinte algoritmo:

1. Verifica se existe um arquivo bun.lock na raiz do projeto. Se existir, usa a versão especificada no lockfile.
2. Caso contrário, varre a árvore para cima em busca de um package.json que inclua "foo" como dependência. Se encontrado, usa a versão semver especificada ou intervalo de versão.
3. Caso contrário, usa latest.

---

Comportamento do cache

Depois de determinar a versão ou intervalo de versões, o Bun irá:

1. Verificar no cache de módulos se existe uma versão compatível. Se existir, usá-la.
2. Ao resolver latest, o Bun verificará se package@latest foi baixado e armazenado em cache nas últimas 24 horas. Se sim, usá-lo.
3. Caso contrário, baixar e instalar a versão apropriada do registro npm.

---

Instalação

Os pacotes são instalados e armazenados em cache em <cache>/<pkg>@<version>, então várias versões do mesmo pacote podem ser armazenadas em cache ao mesmo tempo. Além disso, um symlink é criado em <cache>/<pkg>/<version> para tornar mais rápida a consulta de todas as versões de um pacote que existem no cache.

---

Especificadores de versão

Todo este algoritmo de resolução pode ser interrompido especificando uma versão ou intervalo de versões diretamente na sua instrução de import.

import { z } from "zod@3.0.0"; // versão específica
import { z } from "zod@next"; // tag npm
import { z } from "zod@^3.20.0"; // intervalo semver

---

Benefícios

Esta abordagem de instalação automática é útil por algumas razões:

• Eficiência de espaço — Cada versão de uma dependência existe apenas em um lugar no disco. Isso representa uma enorme economia de espaço e tempo comparado às instalações redundantes por projeto.
• Portabilidade — Para compartilhar scripts simples e gists, seu arquivo fonte é autocontido. Não há necessidade de zipar um diretório contendo seus arquivos de código e configuração. Com especificadores de versão nas instruções import, nem mesmo um package.json é necessário.
• Conveniência — Não há necessidade de executar npm install ou bun install antes de executar um arquivo ou script. Apenas bun run.
• Compatibilidade com versões anteriores — Como o Bun ainda respeita as versões especificadas no package.json se existir, você pode mudar para a resolução no estilo Bun com um único comando: rm -rf node_modules.

---

Limitações

• Sem Intellisense. O auto-complete do TypeScript em IDEs depende da existência de arquivos de declaração de tipo dentro de node_modules. Estamos investigando várias soluções para isso.
• Sem suporte a patch-package

---

FAQ

Como isso é diferente do que o pnpm faz?">

Com o pnpm, você precisa executar pnpm install, que cria uma pasta node_modules de symlinks para o runtime resolver. Em contraste, o Bun resolve dependências em tempo de execução quando você executa um arquivo; não há necessidade de executar nenhum comando install antes. O Bun também não cria uma pasta node_modules.

Como isso é diferente do que o Yarn Plug'N'Play faz?">

Com o Yarn, você deve executar yarn install antes de executar um script. Em contraste, o Bun resolve dependências em tempo de execução quando você executa um arquivo; não há necessidade de executar nenhum comando install antes.

O Yarn Plug'N'Play também usa arquivos zip para armazenar dependências. Isso torna o carregamento de dependências mais lento em tempo de execução, pois leituras de acesso aleatório em arquivos zip tendem a ser mais lentas que a equivalência de busca em disco.

Como isso é diferente do que o Deno faz?">

O Deno requer um especificador npm: antes de cada import npm, não tem suporte a mapas de import via compilerOptions.paths no tsconfig.json, e tem suporte incompleto para configurações de package.json. Ao contrário do Deno, o Bun atualmente não suporta imports por URL.