Bun Runtime: O Que É, Como Instalar e Bun vs Node.js

O Bun runtime é um toolkit para desenvolver e executar aplicações JavaScript e TypeScript. Em um único executável, ele reúne runtime, gerenciador de pacotes, test runner e bundler. Para experimentar, instale o Bun, rode bun --version e execute um arquivo com bun run arquivo.ts.

Resposta curta: Bun é uma alternativa prática ao conjunto Node.js + npm/pnpm + test runner + bundler. Ele pode simplificar o ambiente e acelerar tarefas, mas uma migração deve ser validada com os testes reais do projeto. Historicamente associado a Zig, o Bun incorporou em maio de 2026 uma ampla reescrita do runtime em Rust.

Bun runtime em 30 segundos

O que é Bun?

Bun tenta reduzir a quantidade de ferramentas necessárias no ciclo de desenvolvimento JavaScript. O comando bun cobre quatro funções principais:

• runtime: executa arquivos JavaScript, TypeScript, JSX e TSX;
• package manager: instala dependências e lê projetos do ecossistema npm;
• test runner: executa testes com APIs próprias e compatibilidade com padrões populares;
• bundler: gera bundles para aplicações e bibliotecas.

Isso não significa que todas as ferramentas tradicionais deixam de ser úteis. TypeScript ainda é a autoridade para checagem estática de tipos, e frameworks podem manter seus próprios compiladores, plugins e comandos. A vantagem do Bun é oferecer uma base integrada para tarefas comuns.

O runtime usa JavaScriptCore (JSC), escrito em C++, para analisar, compilar e executar JavaScript. Bun adiciona ao redor da engine o event loop, APIs de arquivos e rede, compatibilidade com Node.js, transpiler, package manager e outras ferramentas.

Como instalar o Bun runtime

Consulte sempre a documentação oficial de instalação, pois os métodos e requisitos podem mudar.

Linux e macOS

curl -fsSL https://bun.com/install | bash

Abra um novo terminal ou carregue novamente a configuração do shell. Depois confirme:

bun --version
bun --revision

Antes de executar um instalador remoto em um ambiente corporativo, revise o script e siga a política de segurança da organização.

Instalação com npm

Se Node.js e npm já estão disponíveis:

npm install -g bun
bun --version

macOS e Linux com Homebrew

brew install oven-sh/bun/bun
bun --version

Windows

No Windows 10 ou superior, use o PowerShell oficial:

powershell -c "irm bun.sh/install.ps1 | iex"

Depois confirme com bun --version. Também há suporte via npm install -g bun, Scoop e Chocolatey quando o PowerShell não for uma opção.

Docker e CI

Para ambientes de container, use a imagem oficial fixando a versão:

FROM oven/bun:1.2
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
CMD ["bun", "run", "src/server.ts"]

Ou execute um comando único sem Dockerfile:

docker run --rm --init -it oven/bun:latest -e "console.log('Olá do Bun')"

Para atualizar uma instalação existente, use bun upgrade — em CI, prefira reinstalar a versão fixada a fazer upgrade em runtime.

No Windows, o comando PowerShell acima é a forma recomendada. Para CI e produção, fixe a versão do Bun em vez de depender implicitamente da release mais recente.

Primeiro programa com Bun

Crie server.ts:

const server = Bun.serve({
  port: 3000,
  fetch(request) {
    const url = new URL(request.url);

    return Response.json({
      runtime: "Bun",
      path: url.pathname,
    });
  },
});

console.log(`Servidor em ${server.url}`);

Execute:

bun run server.ts

Teste em outro terminal:

curl http://localhost:3000/status

Esse exemplo usa Bun.serve, uma API específica do runtime. Se a portabilidade para Node.js ou navegadores for importante, prefira APIs web padronizadas quando possível e isole chamadas específicas do Bun atrás de módulos pequenos.

Comandos essenciais

Criar e executar um projeto

mkdir exemplo-bun
cd exemplo-bun
bun init
bun run index.ts

Instalar dependências

bun install
bun add hono
bun add -d typescript @types/bun
bun remove hono

O bun install lê o package.json e cria ou atualiza o lockfile do projeto. Em CI, use o modo de lockfile congelado para impedir alterações inesperadas:

bun install --frozen-lockfile

Executar scripts do package.json

Com este arquivo:

{
  "scripts": {
    "dev": "bun --watch src/server.ts",
    "typecheck": "tsc --noEmit",
    "test": "bun test"
  }
}

execute:

bun run dev
bun run typecheck
bun test

Bun remove tipos durante a transpilação, mas não substitui a análise completa do compilador TypeScript. Mantenha tsc --noEmit no CI quando o projeto depende de segurança de tipos.

Bun install troca o runtime do projeto?

Não. bun install troca o gerenciador de pacotes, não o processo que executa a aplicação. Você pode instalar dependências com Bun e continuar usando Node.js em produção. Isso permite avaliar a instalação separadamente da migração do runtime.

Também há uma diferença importante em bun run: ao chamar uma CLI cujo arquivo começa com #!/usr/bin/env node, o Bun respeita esse shebang e usa Node.js por padrão. Para testar essa CLI com o runtime Bun, use bun run --bun nome-do-script. Esse comportamento está descrito na documentação oficial de execução do Bun.

Para confirmar o runtime do processo que você está medindo, crie runtime-check.js:

console.log({
  runtime: process.versions.bun ? "Bun" : "Node.js",
  bun: process.versions.bun ?? null,
  nodeCompatibility: process.versions.node,
});

Compare as execuções, se ambos estiverem instalados:

node runtime-check.js
bun run runtime-check.js

A primeira deve imprimir runtime: 'Node.js'; a segunda, runtime: 'Bun' e a versão do Bun. Não use apenas process.versions.node para identificar o runtime: Bun também expõe esse campo por compatibilidade. Para investigar uma CLI ou servidor, coloque a verificação no próprio processo executado; um script separado não comprova qual runtime outra ferramenta usou.

Outro cuidado: uma instalação concluída não prova que todos os scripts de dependências foram executados. Bun controla scripts de ciclo de vida, como postinstall, por uma lista de pacotes confiáveis. Se uma dependência precisar gerar ou baixar um binário, confira a política de lifecycle scripts e trustedDependencies. Revise o pacote e o script antes de autorizá-lo; não libere scripts indiscriminadamente para fazer a migração passar.

Rodar testes

Crie soma.test.ts:

import { expect, test } from "bun:test";

function soma(a: number, b: number) {
  return a + b;
}

test("soma dois números", () => {
  expect(soma(2, 3)).toBe(5);
});

Depois rode:

bun test

Bun vs Node.js vs Deno

Não existe um vencedor universal. A escolha depende de compatibilidade, maturidade exigida, ferramentas da equipe e necessidades de implantação.

Use Bun quando

• você quer experimentar uma toolchain integrada em projeto novo;
• instalação de dependências e tempo de inicialização importam para o fluxo local ou CI;
• o projeto usa JavaScript ou TypeScript convencional;
• a suíte de testes cobre integrações, dependências e comportamento de produção;
• o time aceita validar compatibilidade a cada atualização.

Prefira manter Node.js quando

• a aplicação depende de addons nativos ou APIs específicas sem cobertura no Bun;
• fornecedores e plataformas homologam apenas Node.js;
• a migração não traz ganho mensurável para o projeto;
• estabilidade operacional vale mais do que reduzir ferramentas.

Considere Deno quando

• o projeto prioriza APIs web e o modelo do ecossistema Deno;
• permissões explícitas fazem parte do desenho operacional;
• as ferramentas e a distribuição do Deno combinam melhor com a equipe.

Como testar Bun em um projeto Node.js existente

Não comece substituindo o runtime em produção. Faça uma avaliação reversível:

1. crie uma branch de teste;
2. mantenha o lockfile atual até entender o impacto da troca;
3. execute bun install e registre diferenças de dependências;
4. rode lint, typecheck, testes unitários e integração; confirme o runtime das CLIs e avalie bun run --bun nome-do-script quando houver shebang de Node.js;
5. teste build, migrations, workers, sinais de processo e encerramento gracioso;
6. verifique addons nativos, scripts de pós-instalação e acesso ao sistema de arquivos;
7. compare tempo, consumo de memória e comportamento com carga representativa;
8. fixe a versão aprovada no CI e na imagem de produção.

Um smoke test mínimo pode usar:

bun install --frozen-lockfile
bun run typecheck
bun test
bun run build

A compatibilidade com a sintaxe JavaScript não garante compatibilidade operacional. Observe também variáveis de ambiente, resolução de módulos, streams, conexões, timers e bibliotecas que detectam o runtime.

Bun, Zig e Rust: qual é a relação atual?

Bun se tornou um dos projetos mais conhecidos ligados a Zig. A implementação original usou Zig para construir o runtime e suas ferramentas ao redor do JavaScriptCore. Controle explícito de memória, integração com C/C++, compilação cruzada e um sistema de build integrado fizeram parte da escolha técnica.

Esse contexto mudou. Em maio de 2026, o pull request oficial “Rewrite Bun in Rust” foi incorporado ao projeto. O repositório atual do Bun é majoritariamente Rust e ainda contém componentes em C++, TypeScript, C e outras linguagens. Portanto, dizer apenas que “Bun é escrito em Zig” já não descreve corretamente o estado atual.

A história continua relevante para quem estuda Zig. Ela mostra dois momentos de engenharia:

1. a escolha inicial de Zig, motivada por performance, controle e interoperabilidade;
2. a migração posterior, motivada pela manutenção de uma base grande e pela busca de garantias mais fortes contra problemas de memória.

Para a análise técnica dessa mudança, leia Bun em Rust: o que a reescrita ensina para quem usa Zig. Para o contexto da arquitetura original, veja como o Bun foi construído com Zig.

Cuidados antes de adotar Bun em produção

Compatibilidade não é binária

Uma biblioteca pode importar corretamente e falhar apenas em um caminho raro. Teste filas, uploads, WebSockets, banco de dados, child processes e desligamento do serviço, não apenas o endpoint principal.

Benchmarks precisam representar sua aplicação

Números publicados pelo projeto ajudam a formular hipóteses, mas não substituem medição. Compare versões fixas, mesma máquina, mesma carga, mesmas dependências e métricas de latência, throughput, memória e estabilidade.

Atualizações devem ser controladas

Use uma versão fixa na imagem de container, no gerenciador de toolchain ou no workflow de CI. Leia as notas de release e execute a suíte completa antes de atualizar ambientes compartilhados.

TypeScript ainda precisa de typecheck

Execução direta de .ts significa transpilação conveniente, não prova de correção dos tipos. Separe explicitamente os passos de typecheck, teste e build.

Conclusão

O Bun runtime é uma opção real para executar JavaScript e TypeScript, instalar pacotes, testar código e gerar bundles com uma única ferramenta. Seu melhor uso não depende de promessas genéricas de velocidade, mas de um teste controlado no projeto que você realmente mantém.

Comece pequeno: instale o Bun, rode scripts e testes, meça o resultado e verifique as incompatibilidades. Se a suíte passar e o ganho operacional for claro, avance para CI e ambientes de homologação. Se não passar, Node.js ou Deno continuam sendo escolhas válidas.

Para aprofundar a relação histórica com programação de sistemas, compare outros casos de Zig em produção e explore os tutoriais de Zig.