bun-runtime

name	bun-runtime
description	런타임, 패키지 매니저, 번들러 및 테스트 러너로서의 Bun. Node와 Bun 중 선택 기준, 마이그레이션 참고 사항, Vercel 지원 여부.
origin	ECC

Bun 런타임

Bun은 런타임, 패키지 매니저, 번들러, 테스트 러너를 모두 포함하는 빠른 올인원 JavaScript 런타임이자 툴킷입니다.

사용 시점

• Bun 권장: 신규 JS/TS 프로젝트, 설치/실행 속도가 중요한 스크립트, Bun 런타임을 사용하는 Vercel 배포, 단일 툴체인(실행 + 설치 + 테스트 + 빌드)을 원하는 경우.
• Node 권장: 생태계 호환성이 최대로 필요한 경우, Node를 가정하는 레거시 도구, 또는 특정 의존성이 Bun에서 문제가 있는 것으로 알려진 경우.

다음 경우에 사용하세요: Bun 도입, Node에서 마이그레이션, Bun 스크립트/테스트 작성 또는 디버깅, Vercel이나 기타 플랫폼에서 Bun 설정.

동작 방식

• 런타임: Node와 호환되는 드롭인 런타임(JavaScriptCore 기반, Zig로 구현).
• 패키지 매니저: bun install은 npm/yarn보다 훨씬 빠릅니다. 현재 Bun의 기본 락파일은 bun.lock(텍스트)이며, 이전 버전은 bun.lockb(바이너리)를 사용했습니다.
• 번들러: 앱과 라이브러리를 위한 내장 번들러 및 트랜스파일러.
• 테스트 러너: Jest와 유사한 API를 가진 내장 bun test.

Node에서 마이그레이션: node script.js를 bun run script.js 또는 bun script.js로 바꿉니다. npm install 대신 bun install을 실행하세요. 대부분의 패키지가 동작합니다. npm 스크립트에는 bun run을, npx 방식의 일회성 실행에는 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");
  },
});

모범 사례

• 재현 가능한 설치를 위해 락파일(bun.lock 또는 bun.lockb)을 커밋하세요.
• 스크립트 실행에는 bun run을 선호하세요. TypeScript의 경우 Bun이 .ts를 네이티브로 실행합니다.
• 의존성을 최신 상태로 유지하세요. Bun과 생태계는 빠르게 진화합니다.