Bun Runtime com Claude Code: adoção prática

Bun não é apenas um runtime JavaScript rápido. Na prática, ele reúne runtime, gerenciador de pacotes, executor de scripts, test runner e bundler. Para iniciantes: runtime é a camada que executa JavaScript ou TypeScript; package script é um atalho em package.json; test runner é a ferramenta que encontra e roda testes.

Com Claude Code, a adoção segura não começa trocando Node.js inteiro. Começa com uma prova pequena: scripts com bun run, uma API mínima com Bun.serve, testes com bun test e revisão de riscos de compatibilidade Node antes de produção. Use como referência a documentação Bun, Bun.serve, bun run, Bun test runner e compatibilidade Node.js.

Leia também o guia de API com Claude Code, estratégias de teste e otimização de performance.

Comece com escopo reversível

Peça primeiro uma análise:

Analise este repositório para uma adoção gradual de Bun. Não modifique arquivos ainda. Leia package.json, lockfiles, testes, CI, Docker e uso de APIs Node. Retorne uma tabela com candidatos seguros, candidatos arriscados e comandos de verificação.

Passo	O que testar	Sinal de sucesso
1	bun install em uma branch	O diff de dependências é entendido
2	bun run para scripts	Os scripts mantêm o mesmo sentido
3	bun test em testes focados	Diferenças com Jest aparecem
4	Bun.serve para API pequena	O HTTP é testável e reversível

Exemplo copiável com Bun.serve

mkdir bun-claude-lab
cd bun-claude-lab
bun init -y

{
  "name": "bun-claude-lab",
  "type": "module",
  "scripts": {
    "dev": "bun --watch src/server.ts",
    "start": "bun src/server.ts",
    "test": "bun test",
    "check": "bun test && bun run scripts/runtime-check.ts"
  }
}

// src/server.ts
function json(data: unknown, status = 200): Response {
  return Response.json(data, {
    status,
    headers: { "Cache-Control": "no-store" }
  });
}

const server = Bun.serve({
  port: Number(process.env.PORT ?? 3000),
  async fetch(req) {
    const url = new URL(req.url);

    if (url.pathname === "/health") {
      return json({ ok: true, runtime: "bun" });
    }

    if (url.pathname === "/api/echo" && req.method === "POST") {
      const body = (await req.json().catch(() => null)) as { message?: string } | null;

      if (!body?.message) {
        return json({ error: "message is required" }, 400);
      }

      return json({
        message: body.message.trim(),
        receivedAt: new Date().toISOString()
      }, 201);
    }

    return json({ error: "not_found", pathname: url.pathname }, 404);
  }
});

console.log(`Listening on ${server.url}`);

bun run dev
curl http://localhost:3000/health
curl -X POST http://localhost:3000/api/echo \
  -H "Content-Type: application/json" \
  -d '{"message":"hello from Bun"}'

Testes com bun:test

// src/message.ts
export function normalizeMessage(input: string): string {
  return input.trim().replace(/\s+/g, " ");
}

export function createReply(input: string): { message: string; length: number } {
  const message = normalizeMessage(input);
  if (!message) throw new Error("message must not be empty");
  return { message, length: message.length };
}

// src/message.test.ts
import { describe, expect, test } from "bun:test";
import { createReply, normalizeMessage } from "./message";

describe("message helpers", () => {
  test("normalizes whitespace", () => {
    expect(normalizeMessage("  hello   bun  ")).toBe("hello bun");
  });

  test("creates a reply payload", () => {
    expect(createReply(" Claude Code ")).toEqual({
      message: "Claude Code",
      length: 11
    });
  });

  test("rejects empty messages", () => {
    expect(() => createReply("   ")).toThrow("message must not be empty");
  });
});

bun test
bun test --watch

Compatibilidade Node

// scripts/runtime-check.ts
import { existsSync } from "node:fs";
import { join } from "node:path";

const checks = [
  ["package.json exists", existsSync(join(process.cwd(), "package.json"))],
  ["Bun global is available", typeof Bun !== "undefined"],
  ["fetch is available", typeof fetch === "function"],
  ["Buffer is available", typeof Buffer !== "undefined"]
] as const;

for (const [label, ok] of checks) {
  console.log(`${ok ? "PASS" : "FAIL"} ${label}`);
}

if (checks.some(([, ok]) => !ok)) {
  process.exit(1);
}

bun run check

Casos de uso

O primeiro caso é API interna ou ferramenta administrativa. Bun.serve resolve /health, endpoints JSON, webhooks e demos locais.

O segundo caso é adoção incremental em um projeto Node.js. Produção pode continuar em Node, enquanto bun install, bun run ou bun test reduzem o ciclo local.

O terceiro caso é documentação e treinamento. Um exemplo curto com servidor, curl e testes ajuda o leitor a entender a fronteira do runtime.

Armadilhas comuns

Não assuma compatibilidade Node perfeita. Addons nativos, módulos node:* menos comuns, pacotes CommonJS antigos e streaming precisam de verificação.

Não migre uma suíte Jest grande de uma vez. Mocking, snapshots, fake timers e testes DOM podem exigir ajustes.

Scripts podem mudar de sentido. Em equipe, prefira bun run dev e documente a ordem de flags como bun --watch run dev.

Velocidade não é plano de rollout. CI, Docker, deploy, monitoramento e rollback precisam de revisão própria.

CTA e nota prática

Para praticar, comece pelo cheatsheet gratuito. Para prompts reutilizáveis, padrões CLAUDE.md e material de setup, veja a página de produtos em inglês. Para adoção em equipe, use training e consultoria.

Nota de verificação: este workspace não tem bun instalado, então não afirmo execução local. O exemplo pode ser validado com bun run dev, os dois comandos curl, bun test e bun run check.