bun-runtime

Runtime Bun

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

Quando Usar

• Prefira Bun para: novos projetos JS/TS, scripts onde velocidade de instalação/execução importa, deploys na Vercel com runtime Bun, e quando você quiser uma única ferramenta (executar + instalar + testar + buildar).
• Prefira Node para: máxima compatibilidade com ecossistema, ferramentas legadas que assumem Node, ou quando uma dependência tem problemas conhecidos com Bun.

Use quando: adotar o Bun, migrar do Node, escrever ou depurar scripts/testes Bun, ou configurar o Bun na Vercel ou outras plataformas.

Como Funciona

• Runtime: Runtime compatível com Node (substituto direto, construído sobre JavaScriptCore, implementado em Zig).
• Gerenciador de pacotes: bun install é significativamente mais rápido que npm/yarn. O lockfile é bun.lock (texto) por padrão no Bun atual; versões antigas usavam bun.lockb (binário).
• Bundler: Bundler e transpilador embutidos para aplicações e bibliotecas.
• Executor de testes: bun test embutido com API semelhante ao Jest.

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

Vercel: Defina o runtime como Bun nas configurações do projeto. Build: bun run build ou bun build ./src/index.ts --outdir=dist. Instalação: bun install --frozen-lockfile para deploys reproduzíveis.

Exemplos

Executar e instalar

# Instala dependências (cria/atualiza bun.lock ou bun.lockb)
bun install

# Executa um script ou arquivo
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

// test/example.test.ts
import { expect, test } from "bun:test";

test("add", () => {
  expect(1 + 2).toBe(3);
});

API do Runtime

const file = Bun.file("package.json");
const json = await file.json();

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello");
  },
});

Melhores Práticas

• Faça commit do lockfile (bun.lock ou bun.lockb) para instalações reproduzíveis.
• Prefira bun run para scripts. Para TypeScript, Bun executa .ts nativamente.
• Mantenha as dependências atualizadas; o Bun e o ecossistema evoluem rapidamente.