Migrando uma API Route Next.js para Bun.serve nativo na Vercel

O runtime Bun para Vercel Functions saiu em Beta e está disponível em todos os planos. Como vivo medindo performance percebida, quis testar na prática: pegar uma API Route de Next.js rodando em Node e migrar o handler para Bun.serve puro. Segue o caminho que fiz, com os tropeços incluídos.

O que o Bun runtime é (e o que não é)

Bun é um runtime JavaScript alternativo ao Node.js, com bundler, test runner e package manager embutidos. A doc da Vercel é honesta num ponto que costuma virar hype: Bun é geralmente mais rápido que Node, especialmente em tarefas CPU-bound, mas em alguns casos o Node pode ser mais rápido dependendo das operações da sua função. Ou seja: mede antes de comemorar.

Um detalhe que me poupou tempo: ambos os runtimes rodam sobre Fluid compute e suportam os mesmos recursos principais (streaming, waitUntil, Active CPU). Então a migração não te faz perder features de plataforma.

Passo 1: ligar o runtime no vercel.json

O ponto de entrada é declarar a versão do Bun. Só o major importa; a Vercel gerencia minor e patch automaticamente.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "bunVersion": "1.x"
}

Hoje "1.x" é o único valor válido. Já tentei chutar "1.2" e o deploy reclamou, então fica o aviso.

Passo 2: escolher o modelo de deploy

Aqui está a decisão de arquitetura. Existem dois caminhos para um servidor Bun nativo:

• Framework preset do Bun: um único Bun.serve() roteia toda a aplicação. Precisa de bun.lock, um server.ts na raiz ou em src/, e não exige diretório /api.
• Servidor Bun a partir de /api: cria api/server.ts e a Vercel serve a função em /api/server. Esse modelo convive com um frontend Next.js no mesmo projeto e só requer o bunVersion, sem bun.lock nem preset.

Como meu objetivo era migrar uma API Route dentro de um app Next.js existente, fui de /api/server. Ele só recebe requests de /api/server, o que deixa o resto do app intacto.

Passo 3: reescrever o handler

O ponto-chave da doc: você chama Bun.serve() uma vez, durante o startup do módulo. A Vercel detecta essa chamada e roteia os requests para uma Vercel Function.

// api/server.ts
Bun.serve({
  fetch(request) {
    const url = new URL(request.url);
    return Response.json({
      message: 'Hello from Bun on Vercel',
      pathname: url.pathname,
    });
  },
});

A boa notícia para quem já escreve API Routes modernas: Request e Response são as Web APIs padrão, os mesmos objetos que você usa em app/api/route.ts. A migração do corpo do handler foi quase copiar e colar.

Se quiser rotas nomeadas, dá pra usar a opção routes:

Bun.serve({
  routes: {
    '/health': () => Response.json({ status: 'ok' }),
  },
  fetch() {
    return new Response('Hello from Bun on Vercel');
  },
});

Os tropeços

port e hostname não configuram nada em produção. Elas só valem quando você roda local. Perdi alguns minutos achando que o endpoint público estava ignorando minha config; ele ignora por design.

Roteamento custom com /api exige o path completo. Cada override no vercel.json precisa incluir o prefixo /api/server. Esqueci disso na primeira tentativa e caiu tudo no fetch genérico.

Se você usa Next.js com ISR, precisa mudar os scripts. Os comandos de build e dev têm que rodar sob o Bun:

{
  "scripts": {
    "dev": "bun run --bun next dev",
    "build": "bun run --bun next build"
  }
}

Middleware precisa de config extra. O Routing Middleware funciona igual ao Node depois de setar o bunVersion, mas você ainda tem que fixar runtime como nodejs no middleware.ts.

Outro ponto de atenção: não há source maps automáticos nem request metrics em node:http/node:https no runtime Bun. Métricas via fetch funcionam nos dois. Se você depende de source maps pra debug em produção, pense duas vezes.

Vale a pena?

Para um projeto novo, onde você quer TypeScript e JSX zero-config e tooling moderno, o Bun runtime é um caminho natural. Para migrar algo que já roda bem em Node só atrás de número, a própria Vercel recomenda cautela: se o Node está funcionando e você precisa de source maps ou métricas em node:http, fique onde está. A regra não muda: rode a medição no seu workload real, com cold start e p95 do seu tráfego, antes de decidir.

Fonte: Vercel Docs — Bun Runtime for Functions