bun-runtime

---
name: bun-runtime
description: Bun as runtime, package manager, bundler, and test runner. When to choose Bun vs Node, migration notes, and Vercel support.
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가 있는 곳에서는 Bun API를 선호합니다.

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

## 예시

### 실행 및 설치

```bash
# Install dependencies (creates/updates bun.lock or bun.lockb)
bun install

# Run a script or file
bun run dev
bun run src/index.ts
bun src/index.ts
```

### 스크립트 및 환경 변수

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

### 테스트

```bash
bun test
bun test --watch
```

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

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

### 런타임 API

```typescript
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과 에코시스템은 빠르게 발전합니다.

More agent context in junimnjw/everything-claude-code

189 other files this repository gives its agents, the first 60 shown.