Bun Runtime dengan Claude Code: panduan adopsi praktis

Bun bukan hanya runtime JavaScript yang cepat. Dalam praktik, Bun menggabungkan runtime, package manager, script runner, test runner, dan bundler. Untuk pemula: runtime adalah lapisan yang menjalankan JavaScript atau TypeScript; package script adalah shortcut di package.json; test runner adalah alat yang mencari dan menjalankan test.

Dengan Claude Code, pola aman bukan langsung mengganti seluruh Node.js. Mulai dari bukti kecil: jalankan script dengan bun run, buat API kecil memakai Bun.serve, jalankan bun test, lalu catat risiko kompatibilitas Node sebelum menyentuh production. Rujukan resmi yang relevan adalah Bun docs, Bun.serve HTTP server, bun run, Bun test runner, dan Node.js compatibility.

Untuk konteks lanjutan, baca panduan API Claude Code, strategi testing, dan optimasi performance.

Mulai dari scope yang bisa dibatalkan

Minta Claude Code melakukan audit dulu:

Periksa repository ini untuk adopsi Bun bertahap. Jangan ubah file dulu. Baca package.json, lockfile, test setup, CI, Docker, dan penggunaan API Node. Buat tabel kandidat aman, kandidat berisiko, dan command verifikasi.

Langkah	Yang dicoba	Tanda berhasil
1	bun install di branch	Diff dependency bisa dijelaskan
2	bun run untuk scripts	Makna script tidak berubah
3	bun test pada test kecil	Perbedaan dengan Jest terlihat
4	Bun.serve untuk API kecil	Perilaku HTTP bisa dites

Contoh Bun.serve yang bisa disalin

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"}'

Test dengan 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

Cek kompatibilitas 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

Use case konkret

Use case pertama adalah API internal atau admin tool. Bun.serve cukup untuk /health, endpoint JSON, webhook receiver, dan demo lokal.

Use case kedua adalah adopsi bertahap di project Node.js. Production bisa tetap memakai Node, sementara bun install, bun run, atau bun test dicoba untuk mempercepat loop lokal.

Use case ketiga adalah materi belajar dan dokumentasi. Contoh kecil dengan server, curl, dan test membuat pembaca bisa memahami batas runtime tanpa framework besar.

Pitfall yang harus direview

Pertama, jangan menganggap kompatibilitas Node selalu identik. Native addon, modul node:* yang jarang dipakai, package CommonJS lama, dan streaming perlu dicek terpisah.

Kedua, jangan memindahkan seluruh test Jest sekaligus. Mocking, snapshot, fake timer, dan DOM testing sering membutuhkan penyesuaian.

Ketiga, package scripts bisa berubah makna. Untuk tim, gunakan bun run dev secara eksplisit dan dokumentasikan urutan flag seperti bun --watch run dev.

Keempat, kecepatan bukan strategi rollout. CI, Docker, target deploy, monitoring, dan rollback tetap harus dirancang.

CTA dan catatan verifikasi

Untuk latihan pribadi, mulai dari cheatsheet gratis. Untuk prompt reusable, pola CLAUDE.md, dan material setup, bandingkan halaman produk Inggris. Untuk adopsi tim, gunakan training dan consultation agar kompatibilitas Node, CI, dan rollback jelas.

Catatan praktik: workspace ini tidak memiliki command bun, jadi artikel ini tidak mengklaim hasil eksekusi lokal. Contoh dapat diverifikasi dengan bun run dev, dua command curl, bun test, dan bun run check.