Runtime Bun

Bun é um runtime e toolkit JavaScript tudo-em-um e rápido: runtime, gerenciador de pacotes, bundler e test runner.

Quando Usar

• Prefira Bun para: novos projetos JS/TS, scripts onde a velocidade de instalação/execução importa, deploys Vercel com runtime Bun, e quando você quer uma única toolchain (executar + instalar + testar + construir).
• Prefira Node para: compatibilidade máxima com o ecossistema, tooling legado que assume Node, ou quando uma dependência tem problemas conhecidos com Bun.

Use quando: adotando Bun, migrando do Node, escrevendo ou depurando scripts/testes Bun, ou configurando Bun no Vercel ou outras plataformas.

Como Funciona

• Versão base: as orientações abaixo visam o Bun 1.4.x. Verifique a versão atual com bun --version antes de confiar em nomes de flags, pois as flags da CLI podem mudar entre lançamentos.
• Runtime: Runtime compatível com Node "drop-in", construído sobre JavaScriptCore. A partir do Bun 1.4, o próprio runtime é implementado em Rust (migrado de Zig). Não é 100% compatível com Node — alguns add-ons nativos, APIs internas menos comuns node: e pacotes que dependem de internals específicos do Node ainda podem falhar; verifique antes de depender dele em produção.
• Gerenciador de pacotes: Bun inclui um gerenciador de pacotes; o desempenho da instalação depende do projeto, condições de rede e estado do cache. O lockfile é bun.lock (texto) por padrão no Bun atual; versões mais antigas usavam bun.lockb (binário) — Bun ainda lê esse formato para migração, mas novos projetos devem usar bun.lock.
• Bundler: Bundler e transpiler integrados para aplicativos e bibliotecas.
• Test runner: bun test integrado com uma API semelhante à do Jest.

Migração do Node: Substitua node script.js por bun run script.js ou bun script.js. Execute bun install em vez de npm install; a maioria dos pacotes funciona. Use bun run para scripts npm; bun x para execuções únicas no estilo npx. Built-ins do Node são suportados; prefira APIs Bun onde elas existem para melhor desempenho.

Comandos de pacotes e workspaces: bun add <pkg> / bun remove <pkg> / bun update [pkg] gerenciam dependências; bun outdated lista dependências desatualizadas. bun pm ls lista as dependências do projeto e as versões resolvidas usando o lockfile; --all inclui dependências transitivas. Não é uma verificação de integridade do conteúdo dos arquivos instalados. bun audit consulta avisos do registro usando nomes de pacotes e versões de bun.lock; não modifica package.json, bun.lock ou node_modules. Revise os destinos aprovados antes de enviar metadados de pacotes privados. Pacotes cujo registro com escopo não possui um endpoint de aviso são ignorados e não afetam o código de saída. bun audit fix atualiza e instala dependências, alterando o lockfile e os pacotes instalados e, às vezes, pinos de versão diretos; revise-o como uma operação de instalação modificadora, incluindo scripts de ciclo de vida aplicáveis. bun dedupe colapsa instalações duplicadas, e bun prune remove pacotes não mais referenciados. Monorepos usam um array raiz workspaces em package.json (mesma convenção que npm/yarn); execute um script em um workspace com bun run --filter <pkg-name> <script>.

APIs integradas: use-as antes de adicionar uma dependência — Bun.file / Bun.write para I/O de arquivos, bun:sqlite para um banco de dados SQLite embarcado, Bun.serve para um servidor HTTP/WebSocket, Bun.sql para bancos de dados SQL, Bun.redis para Redis, e Bun.S3Client para armazenamento de objetos compatível com S3. Veja as notas de lançamento 1.4 para o restante das novidades.

Vercel: Defina bunVersion: "1.4.x" em vercel.json para usar Bun 1.4 (runtime Rust). Veja documentação do runtime Bun do Vercel. Build: bun run build ou bun build ./src/index.ts --outdir=dist. Instalação: bun install --frozen-lockfile para deploys reproduzíveis.

Referência: Notas de lançamento Bun 1.4.

Exemplos

Executar e instalar

# Install dependencies (creates/updates bun.lock)
bun install

# Run a script or file
bun run dev
bun run src/index.ts
bun src/index.ts

Scripts e env

bun run --env-file=.env dev
FOO=bar bun run script.ts

Testes

bun test
bun test --watch