bun-runtime

name	bun-runtime
description	런타임, 패키지 매니저, 번들러, 테스트 러너로서의 Bun. Bun과 Node 중 언제 무엇을 고를지, 마이그레이션 참고, Vercel 지원을 다룬다.
origin	ECC

Bun Runtime

Bun은 빠른 올인원 JavaScript 런타임 겸 툴체인이다. 런타임, 패키지 매니저, 번들러, 테스트 러너를 하나로 제공한다.

언제 사용할지

• Bun 선호: 새 JS/TS 프로젝트, 설치/실행 속도가 중요한 스크립트, Bun 런타임 기반 Vercel 배포, 하나의 툴체인(run + install + test + build)을 원할 때
• Node 선호: 생태계 호환성이 최우선일 때, Node를 가정한 레거시 툴링이 있을 때, 특정 의존성이 Bun에서 문제를 보일 때

즉, Bun 도입, Node에서 마이그레이션, Bun 스크립트/테스트 작성 또는 디버깅, Vercel 같은 플랫폼에서 Bun을 설정할 때 사용한다.

동작 방식

• Runtime: Node 호환 드롭인 런타임(JavaScriptCore 기반, Zig 구현)
• Package manager: bun install은 npm/yarn보다 훨씬 빠르다. 현재 Bun의 기본 lockfile은 bun.lock(텍스트)이고, 구버전은 bun.lockb(바이너리)를 사용했다
• Bundler: 앱과 라이브러리를 위한 내장 번들러 및 트랜스파일러
• Test runner: Jest 유사 API를 제공하는 내장 bun test

Node에서 마이그레이션: node script.js를 bun run script.js 또는 bun script.js로 바꾼다. npm install 대신 bun install을 실행하면 되고 대부분의 패키지는 그대로 동작한다. npm script는 bun run, 일회성 실행은 bun x를 사용한다. Node 내장 모듈도 지원되지만, 성능이 더 좋다면 Bun API를 우선한다.

Vercel: 프로젝트 설정에서 런타임을 Bun으로 지정한다. 빌드 예: bun run build, bun build ./src/index.ts --outdir=dist. 재현 가능한 배포를 위해 설치는 bun install --frozen-lockfile을 사용한다.

예시

실행과 설치

# 의존성 설치 (bun.lock 또는 bun.lockb 생성/업데이트)
bun install

# 스크립트 또는 파일 실행
bun run dev
bun run src/index.ts
bun src/index.ts

스크립트와 환경 변수

bun run --env-file=.env dev
FOO=bar bun run script.ts

테스트

bun test
bun test --watch

// test/example.test.ts
import { expect, test } from "bun:test";

test("add", () => {
  expect(1 + 2).toBe(3);
});

런타임 API

const file = Bun.file("package.json");
const json = await file.json();

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello");
  },
});

베스트 프랙티스

• 재현 가능한 설치를 위해 lockfile(bun.lock 또는 bun.lockb)을 커밋한다
• 스크립트 실행은 bun run을 기본으로 쓴다. TypeScript는 Bun이 .ts를 네이티브로 실행한다
• Bun과 생태계는 빠르게 변하므로 의존성을 최신으로 유지한다