bun-runtime

name	bun-runtime
description	런타임, 패키지 관리자, 번들러 및 테스트 러너로서의 Bun. Bun 대 Node 선택 시기, 마이그레이션 참고 사항 및 Vercel 지원.
origin	ECC

Bun 런타임 (Bun Runtime)

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("더하기", () => {
  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과 그 생태계는 빠르게 진화하고 있습니다.