Bun Runtime mit Claude Code sicher einführen

Bun ist mehr als ein schneller JavaScript-Runner. Für die Praxis ist wichtig, dass Bun Runtime, Package Manager, Script Runner, Test Runner und Bundler in einem Werkzeug bündelt. Eine Runtime ist die Schicht, die JavaScript oder TypeScript ausführt. Ein package script ist ein Kurzkommando in package.json. Ein test runner findet und startet Tests.

Mit Claude Code sollte die Einführung nicht als harter Node.js-Austausch beginnen. Sicherer ist ein kleiner, rückbaubarer Nachweis: bun run für Scripts, ein kleines Bun.serve-API, bun test für fokussierte Tests und eine Liste der Node-Kompatibilitätsrisiken. Offizielle Grundlagen stehen in den Bun Docs, beim Bun.serve HTTP server, bei bun run, beim Bun test runner und auf der Seite zur Node.js-Kompatibilität.

Passende interne Links sind der Claude Code API Development Guide, die Testing-Strategien und die Performance-Optimierung.

Umfang zuerst begrenzen

Gib Claude Code zuerst eine Analyseaufgabe:

Prüfe dieses Repository auf eine schrittweise Bun-Einführung. Ändere noch keine Dateien. Lies package.json, Lockfiles, Testsetup, CI, Docker-Dateien und Node-API-Nutzung. Erstelle eine Tabelle mit sicheren Kandidaten, riskanten Kandidaten und Verifikationsbefehlen.

Schritt	Versuch	Erfolgskriterium
1	bun install in einem Branch	Dependency-Diff ist erklärbar
2	bun run für Scripts	Bedeutung der Scripts bleibt gleich
3	bun test für kleine Tests	Jest-spezifische Lücken sind sichtbar
4	Bun.serve für ein kleines API	HTTP-Verhalten ist testbar

Kopierbares Bun.serve-Beispiel

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

Tests mit 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

Node-Kompatibilität prüfen

// 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

Drei passende Use Cases

Erstens eignet sich Bun für kleine interne APIs, Admin-Werkzeuge und Webhook-Prototypen. Bun.serve reicht für /health, JSON-Endpoints und lokale Demos.

Zweitens kann ein Node.js-Projekt Bun nur im Entwicklungsloop testen. Production bleibt zunächst auf Node.js, während bun install, bun run oder bun test lokal geprüft werden.

Drittens ist Bun gut für Lernmaterial und technische Artikel. Ein kompaktes Beispiel mit Server, curl und Test ist für Leser leichter nachzubauen als ein komplettes Framework.

Typische Fallstricke

Der erste Fallstrick ist blinder Glaube an vollständige Node-Gleichheit. Native Addons, seltene node:*-Module, alte CommonJS-Pakete und Streaming sollten separat geprüft werden.

Der zweite Fallstrick ist eine zu schnelle Jest-Migration. bun:test ist vertraut, aber Mocking, Snapshots, Fake Timer und DOM-Tests brauchen einen eigenen Review.

Der dritte Fallstrick sind Scripts mit veränderter Bedeutung. Für Teams ist bun run dev klarer als Abkürzungen. Dokumentiere auch Flag-Reihenfolge wie bun --watch run dev.

Der vierte Fallstrick ist Geschwindigkeit ohne Rollout-Plan. CI, Docker, Deploy-Ziel, Monitoring und Rollback entscheiden, ob Bun produktionsreif für euer System ist.

CTA und Verifikationsnotiz

Für den Einstieg hilft das kostenlose Cheatsheet. Wiederverwendbare Prompts, CLAUDE.md-Muster und Setup-Material liegen auf der englischen Produktseite. Für Team-Rollout, Node-Kompatibilität, CI und Rollback passt Training und Beratung.

Verifikationsnotiz: In diesem Workspace ist bun nicht installiert. Deshalb wird kein lokaler Lauf behauptet. Das Beispiel ist so aufgebaut, dass es mit bun run dev, den zwei curl-Befehlen, bun test und bun run check überprüft werden kann.