Bun em Produção: O Que Funciona, O Que Não Funciona e O Que Me Surpreendeu | Akousa

bash

# Verificar sua versão do Bun
bun --version
 
# Executar um arquivo TypeScript diretamente — sem tsconfig, sem etapa de compilação
bun run server.ts
 
# Instalar pacotes
bun install
 
# Executar testes
bun test
 
# Gerar bundle para produção
bun build ./src/index.ts --outdir ./dist

bash

# Benchmark de instalação limpa — deletar node_modules e lockfile primeiro
rm -rf node_modules bun.lockb package-lock.json
 
# Tempo do npm
time npm install
# Real: ~18.4s (projeto de tamanho médio típico)
 
# Tempo do bun
time bun install
# Real: ~2.1s

bash

# Benchmark rápido e simples com bombardier
# Testando uma resposta simples "Hello World"
 
# Servidor Bun
bombardier -c 100 -d 10s http://localhost:3000
# Requests/sec: ~105.000
 
# Node.js (módulo http nativo)
bombardier -c 100 -d 10s http://localhost:3001
# Requests/sec: ~48.000
 
# Node.js (Express)
bombardier -c 100 -d 10s http://localhost:3002
# Requests/sec: ~15.000

typescript

// fibonacci.ts — isso é limitado pelo motor, não pelo runtime
function fib(n: number): number {
  if (n <= 1) return n;
  return fib(n - 1) + fib(n - 2);
}
 
const start = performance.now();
console.log(fib(42));
console.log(`${(performance.now() - start).toFixed(0)}ms`);

bash

# Instalar hyperfine para benchmarking adequado
brew install hyperfine  # macOS
# ou: cargo install hyperfine
 
# Benchmark de inicialização + execução da sua aplicação real
hyperfine --warmup 3 \
  'node dist/server.js' \
  'bun src/server.ts' \
  --prepare 'sleep 0.1'
 
# Para servidores HTTP, use bombardier ou wrk
# Importante: teste com payloads realistas, não "Hello World"
bombardier -c 50 -d 30s -l http://localhost:3000/api/users
 
# Comparação de memória
/usr/bin/time -v node server.js  # Linux
/usr/bin/time -l bun server.ts   # macOS

bash

# Instalar todas as dependências do package.json
bun install
 
# Adicionar uma dependência
bun add express
 
# Adicionar uma dependência de desenvolvimento
bun add -d vitest
 
# Remover uma dependência
bun remove express
 
# Atualizar uma dependência
bun update express
 
# Instalar uma versão específica
bun add express@4.18.2

bash

# Instalar dependências para todos os workspaces
bun install
 
# Executar um script em um workspace específico
bun run --filter packages/shared build
 
# Adicionar uma dependência a um workspace específico
bun add react --filter apps/web

bash

# Passo 1: Deletar lockfile existente e node_modules
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
 
# Passo 2: Instalar com Bun
bun install
 
# Passo 3: Verificar se sua aplicação ainda funciona
bun run dev
# ou: node dist/server.js  (gerenciador de pacotes Bun, runtime Node)

typescript

// Todos estes funcionam como esperado no Bun
import fs from "node:fs";
import path from "node:path";
import crypto from "node:crypto";
import { Buffer } from "node:buffer";
import { EventEmitter } from "node:events";
import { Readable, Writable } from "node:stream";
import http from "node:http";
import https from "node:https";
import { URL, URLSearchParams } from "node:url";
import os from "node:os";
import child_process from "node:child_process";

typescript

// Isso NÃO funcionará no Bun — específico do V8
const v8 = require("v8");
v8.serialize({ data: "test" });
 
// Isso FUNCIONARÁ — use o equivalente do Bun ou uma abordagem cross-runtime
const encoded = new TextEncoder().encode(JSON.stringify({ data: "test" }));

typescript

const server = Bun.serve({
  port: 3000,
  fetch(req) {
    const url = new URL(req.url);
 
    if (url.pathname === "/") {
      return new Response("Hello from Bun!", {
        headers: { "Content-Type": "text/plain" },
      });
    }
 
    if (url.pathname === "/api/users") {
      const users = [
        { id: 1, name: "Alice" },
        { id: 2, name: "Bob" },
      ];
      return Response.json(users);
    }
 
    return new Response("Not Found", { status: 404 });
  },
});
 
console.log(`Server running at http://localhost:${server.port}`);

typescript

import { Database } from "bun:sqlite";
 
const db = new Database("app.db");
db.run(`
  CREATE TABLE IF NOT EXISTS todos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    completed INTEGER DEFAULT 0,
    created_at TEXT DEFAULT (datetime('now'))
  )
`);
 
const server = Bun.serve({
  port: process.env.PORT || 3000,
 
  async fetch(req) {
    const url = new URL(req.url);
    const method = req.method;
 
    try {
      // GET /api/todos
      if (url.pathname === "/api/todos" && method === "GET") {
        const todos = db.query("SELECT * FROM todos ORDER BY created_at DESC").all();
        return Response.json(todos);
      }
 
      // POST /api/todos
      if (url.pathname === "/api/todos" && method === "POST") {
        const body = await req.json();
 
        if (!body.title || typeof body.title !== "string") {
          return Response.json({ error: "Title is required" }, { status: 400 });
        }
 
        const stmt = db.prepare("INSERT INTO todos (title) VALUES (?) RETURNING *");
        const todo = stmt.get(body.title);
        return Response.json(todo, { status: 201 });
      }
 
      // DELETE /api/todos/:id
      const deleteMatch = url.pathname.match(/^\/api\/todos\/(\d+)$/);
      if (deleteMatch && method === "DELETE") {
        const id = parseInt(deleteMatch[1], 10);
        db.run("DELETE FROM todos WHERE id = ?", [id]);
        return new Response(null, { status: 204 });
      }
 
      return Response.json({ error: "Not found" }, { status: 404 });
    } catch (error) {
      console.error("Request error:", error);
      return Response.json({ error: "Internal server error" }, { status: 500 });
    }
  },
});
 
console.log(`Server running on port ${server.port}`);

typescript

// Lendo arquivos
const file = Bun.file("./config.json");
const text = await file.text(); // Ler como string
const json = await file.json(); // Fazer parse como JSON diretamente
const bytes = await file.arrayBuffer(); // Ler como ArrayBuffer
const stream = file.stream(); // Ler como ReadableStream
 
// Metadados do arquivo
console.log(file.size); // Tamanho em bytes
console.log(file.type); // Tipo MIME (ex.: "application/json")
 
// Escrevendo arquivos
await Bun.write("./output.txt", "Hello, World!");
await Bun.write("./data.json", JSON.stringify({ key: "value" }));
await Bun.write("./copy.png", Bun.file("./original.png"));
 
// Escrever o body de uma Response em um arquivo
const response = await fetch("https://example.com/data.json");
await Bun.write("./downloaded.json", response);

typescript

const server = Bun.serve({
  port: 3000,
 
  fetch(req, server) {
    const url = new URL(req.url);
 
    if (url.pathname === "/ws") {
      const upgraded = server.upgrade(req, {
        data: {
          userId: url.searchParams.get("userId"),
          joinedAt: Date.now(),
        },
      });
 
      if (!upgraded) {
        return new Response("WebSocket upgrade failed", { status: 400 });
      }
      return undefined;
    }
 
    return new Response("Use /ws for WebSocket connections");
  },
 
  websocket: {
    open(ws) {
      console.log(`Client connected: ${ws.data.userId}`);
      ws.subscribe("chat");
    },
 
    message(ws, message) {
      // Broadcast para todos os inscritos
      server.publish("chat", `${ws.data.userId}: ${message}`);
    },
 
    close(ws) {
      console.log(`Client disconnected: ${ws.data.userId}`);
      ws.unsubscribe("chat");
    },
  },
});

typescript

import { Database } from "bun:sqlite";
 
// Abrir ou criar um banco de dados
const db = new Database("myapp.db");
 
// Modo WAL para melhor performance de leitura concorrente
db.exec("PRAGMA journal_mode = WAL");
 
// Criar tabelas
db.run(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    email TEXT UNIQUE NOT NULL,
    name TEXT NOT NULL,
    created_at TEXT DEFAULT (datetime('now'))
  )
`);
 
// Prepared statements (reutilizáveis, mais rápidos para consultas repetidas)
const insertUser = db.prepare("INSERT INTO users (email, name) VALUES ($email, $name) RETURNING *");
 
const findByEmail = db.prepare("SELECT * FROM users WHERE email = $email");
 
// Uso
const user = insertUser.get({
  $email: "alice@example.com",
  $name: "Alice",
});
console.log(user); // { id: 1, email: "alice@example.com", name: "Alice", ... }
 
// Transações
const insertMany = db.transaction((users: { email: string; name: string }[]) => {
  for (const user of users) {
    insertUser.run({ $email: user.email, $name: user.name });
  }
  return users.length;
});
 
const count = insertMany([
  { email: "bob@example.com", name: "Bob" },
  { email: "carol@example.com", name: "Carol" },
]);
console.log(`Inserted ${count} users`);

typescript

// math.test.ts
import { describe, it, expect } from "bun:test";
 
describe("math utilities", () => {
  it("adds numbers correctly", () => {
    expect(1 + 2).toBe(3);
  });
 
  it("handles floating point", () => {
    expect(0.1 + 0.2).toBeCloseTo(0.3);
  });
});

bash

# Executar todos os testes
bun test
 
# Executar arquivo específico
bun test math.test.ts
 
# Executar testes que correspondam a um padrão
bun test --test-name-pattern "adds numbers"
 
# Modo watch
bun test --watch
 
# Cobertura
bun test --coverage

typescript

import { describe, it, expect, mock, spyOn } from "bun:test";
import { fetchUsers } from "./api";
 
// Mock de um módulo
mock.module("./database", () => ({
  query: mock(() => [{ id: 1, name: "Alice" }]),
}));
 
describe("fetchUsers", () => {
  it("returns users from database", async () => {
    const users = await fetchUsers();
    expect(users).toHaveLength(1);
    expect(users[0].name).toBe("Alice");
  });
});
 
// Espionar um método de objeto
describe("console", () => {
  it("tracks console.log calls", () => {
    const logSpy = spyOn(console, "log");
    console.log("test message");
    expect(logSpy).toHaveBeenCalledWith("test message");
    logSpy.mockRestore();
  });
});

bash

# Gerar bundle de um único entry point
bun build ./src/index.ts --outdir ./dist
 
# Gerar bundle para diferentes alvos
bun build ./src/index.ts --outdir ./dist --target browser
bun build ./src/index.ts --outdir ./dist --target bun
bun build ./src/index.ts --outdir ./dist --target node
 
# Minificar
bun build ./src/index.ts --outdir ./dist --minify
 
# Gerar sourcemaps
bun build ./src/index.ts --outdir ./dist --sourcemap external

typescript

const result = await Bun.build({
  entrypoints: ["./src/index.ts", "./src/worker.ts"],
  outdir: "./dist",
  target: "browser",
  minify: {
    whitespace: true,
    identifiers: true,
    syntax: true,
  },
  splitting: true, // Code splitting
  sourcemap: "external",
  external: ["react", "react-dom"], // Não incluir no bundle
  naming: "[dir]/[name]-[hash].[ext]",
  define: {
    "process.env.NODE_ENV": JSON.stringify("production"),
  },
});
 
if (!result.success) {
  console.error("Build failed:");
  for (const log of result.logs) {
    console.error(log);
  }
  process.exit(1);
}
 
for (const output of result.outputs) {
  console.log(`${output.path} — ${output.size} bytes`);
}

typescript

// utils.ts
export function used() {
  return "I'll be in the bundle";
}
 
export function unused() {
  return "I'll be tree-shaken away";
}
 
// index.ts
import { used } from "./utils";
console.log(used());

typescript

// build-info.ts — este arquivo roda em TEMPO DE BUILD, não em runtime
export function getBuildInfo() {
  return {
    builtAt: new Date().toISOString(),
    gitSha: require("child_process").execSync("git rev-parse --short HEAD").toString().trim(),
    nodeVersion: process.version,
  };
}

typescript

// app.ts
import { getBuildInfo } from "./build-info" with { type: "macro" };
 
// getBuildInfo() executa em tempo de bundle
// O resultado é inlined como um valor estático
const info = getBuildInfo();
console.log(`Built at ${info.builtAt}, commit ${info.gitSha}`);

dockerfile

FROM oven/bun:1 AS base
WORKDIR /app
 
# Instalar dependências
FROM base AS deps
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production
 
# Build (se necessário)
FROM base AS build
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build
 
# Produção
FROM base AS production
WORKDIR /app
 
# Não rodar como root
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
USER appuser
 
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./
 
EXPOSE 3000
CMD ["bun", "run", "dist/server.js"]

dockerfile

# Estágio de build: imagem completa do Bun com todas as dependências
FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun build ./src/index.ts --target bun --outdir ./dist --minify
 
# Estágio de runtime: imagem base menor
FROM oven/bun:1-slim AS runtime
WORKDIR /app
 
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
USER appuser
 
COPY --from=builder /app/dist ./dist
 
EXPOSE 3000
CMD ["bun", "run", "dist/index.js"]

bash

# Compilar sua aplicação em um executável standalone
bun build --compile ./src/server.ts --outfile server
 
# A saída é um binário standalone — não precisa de Bun ou Node.js para rodar
./server

dockerfile

# Imagem Docker ultra-mínima usando binário compilado
FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun build --compile ./src/server.ts --outfile server
 
# Imagem final — apenas o binário
FROM debian:bookworm-slim
WORKDIR /app
 
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser
USER appuser
 
COPY --from=builder /app/server ./server
 
EXPOSE 3000
CMD ["./server"]

bash

# Imagem Node.js
docker images | grep node
# node:20-slim    ~180MB
 
# Imagem Bun
docker images | grep bun
# oven/bun:1-slim  ~130MB
 
# Binário compilado em debian:bookworm-slim
# ~80MB base + ~70MB binário = ~150MB total
 
# vs. Alpine com Node.js
# node:20-alpine   ~130MB + node_modules

json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "bun",
      "request": "launch",
      "name": "Debug Bun",
      "program": "${workspaceFolder}/src/server.ts",
      "cwd": "${workspaceFolder}",
      "stopOnEntry": false,
      "watchMode": false
    }
  ]
}

bash

# Comparar contagem de dependências
# Um projeto típico Express + SQLite + WebSocket:
npm ls --all | wc -l
# ~340 pacotes
 
# A mesma funcionalidade com embutidos do Bun:
bun pm ls --all | wc -l
# ~12 pacotes (apenas seu código de aplicação)

typescript

// Use opções do Bun.serve() para ajuste de produção
Bun.serve({
  port: 3000,
 
  // Aumentar tamanho máximo do body da request (padrão é 128MB)
  maxRequestBodySize: 1024 * 1024 * 50, // 50MB
 
  // Habilitar modo de desenvolvimento para melhores páginas de erro
  development: process.env.NODE_ENV !== "production",
 
  // Reusar porta (útil para reinícios sem downtime)
  reusePort: true,
 
  fetch(req) {
    return new Response("OK");
  },
});

typescript

// Usar Bun.Transpiler para transformação de código em runtime
const transpiler = new Bun.Transpiler({
  loader: "tsx",
  target: "browser",
});
 
const code = transpiler.transformSync(`
  const App: React.FC = () => <div>Hello</div>;
  export default App;
`);

bash

# Flags de uso de memória do Bun
bun --smol run server.ts  # Reduzir footprint de memória (ligeiramente mais lento)
 
# Definir tamanho máximo do heap
BUN_JSC_forceRAMSize=512000000 bun run server.ts  # ~512MB limite

typescript

// O fetch do Node.js 18+ e o fetch do Bun são ligeiramente diferentes
// em como lidam com certos headers e redirecionamentos
 
// O Bun segue redirecionamentos por padrão (como navegadores)
// O fetch do Node.js também segue redirecionamentos, mas o comportamento
// com certos status codes (303, 307, 308) pode diferir
 
const response = await fetch("https://api.example.com/data", {
  redirect: "manual", // Ser explícito sobre tratamento de redirecionamento
});

typescript

// O Bun sai quando o event loop está vazio
// O Node.js às vezes continua rodando devido a handles pendentes
 
// Se seu script Bun sai inesperadamente, algo não está
// mantendo o event loop ativo
 
// Isso vai sair imediatamente no Bun:
setTimeout(() => {}, 0);
 
// Isso vai continuar rodando:
setTimeout(() => {}, 1000);
// (Bun sai após o timeout disparar)

typescript

// O Bun tem seus próprios padrões de tsconfig
// Se você está compartilhando um projeto entre Bun e Node.js,
// seja explícito no seu tsconfig.json:
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "types": ["bun-types"]  // Adicionar definições de tipo do Bun
  }
}

bash

# O Bun tem modo watch embutido
bun --watch run server.ts
 
# Isso reinicia o processo nas mudanças de arquivo
# Não é HMR (Hot Module Replacement) — é um restart completo
# Mas como o Bun inicia tão rápido, parece instantâneo

toml

# bunfig.toml — arquivo de configuração do Bun (opcional)
 
[install]
# Usar um registry privado
registry = "https://npm.mycompany.com"
 
# Registries com escopo
[install.scopes]
"@mycompany" = "https://npm.mycompany.com"
 
[test]
# Configuração de testes
coverage = true
coverageReporter = ["text", "lcov"]
 
[run]
# Shell a usar para bun run
shell = "bash"

O Que o Bun Realmente É

As Alegações de Velocidade — Benchmarks Honestos

Tempo de Inicialização

Instalação de Pacotes

Throughput do Servidor HTTP

Onde a Diferença É Insignificante

Como Executar Seus Próprios Benchmarks

Bun como Gerenciador de Pacotes

O Básico

A Situação do Lockfile

Suporte a Workspaces

Compatibilidade com Projetos Existentes

Compatibilidade com Node.js

O Que Funciona

O Que Não Funciona (ou Tem Problemas)

O Rastreador de Compatibilidade

APIs Embutidas do Bun

Bun.serve() — O Servidor HTTP Embutido

Bun.file() e Bun.write() — I/O de Arquivo

Suporte WebSocket Embutido

SQLite Embutido com bun:sqlite

Test Runner do Bun

Uso Básico

Mocking

Bun Test vs. Vitest — Minha Comparação Honesta

Bundler do Bun

Bundling Básico

API Programática

Tree-Shaking

Onde o Bun Build Fica Aquém

Macros do Bun

Usando Bun com Next.js

O Que Funciona Hoje

O Que Ainda É Experimental

Minha Recomendação para Next.js

Docker com Bun

Dockerfile Básico

Build Multi-Estágio para Imagem Mínima

Compilando para um Único Binário

Comparação de Tamanho

Padrões de Migração

Fase 1: Apenas Gerenciador de Pacotes (Risco Zero)

Fase 2: Scripts e Tooling

Fase 3: Test Runner (Risco Médio)

Fase 4: Runtime para Novos Serviços (Risco Calculado)

Fase 5: Migração de Runtime (Avançado)

Variáveis de Ambiente e Configuração

Tratamento de Erros e Depuração

Considerações de Segurança

Ajuste de Performance

Armadilhas Comuns

1. Comportamento Global do Fetch Difere

2. Comportamento de Saída do Processo

3. Configuração do TypeScript

4. Hot Reload em Desenvolvimento

5. O Arquivo de Configuração bunfig.toml

Meu Veredito

Onde Eu Uso Bun Hoje

Onde Eu Fico com Node.js

O Que Eu Estou Acompanhando

Conclusão

Posts Relacionados

Regex Cheat Sheet 2026 — Regular Expressions Made Simple

How to Compress Images Without Losing Quality: The Complete 2026 Guide

5. O Arquivo de Configuração `bunfig.toml`