liminfoBun Runtime Reference
Bun 런타임 API, CLI, 패키지 매니저, 테스트 러너 레퍼런스
Bun Runtime Reference 소개
Bun 런타임 레퍼런스는 JavaScript 런타임, 패키지 매니저, 번들러, 테스트 러너를 하나로 통합한 Bun의 핵심 API를 검색 가능한 치트 시트로 정리한 자료입니다. 런타임 섹션에서는 fetch 핸들러 하나로 HTTP/WebSocket 서버를 만드는 Bun.serve(), 지연 로딩 방식의 파일 참조를 생성하는 Bun.file(), 문자열·Blob·Response를 디스크에 쓰는 Bun.write(), 자식 프로세스를 실행하고 stdout을 표준 Web API Response 스트림으로 읽는 Bun.spawn() 등 가장 많이 쓰이는 내장 API를 다룹니다.
CLI 섹션에서는 npm보다 10~25배 빠른 패키지 설치 도구인 bun install, 별도 트랜스파일 없이 TypeScript 파일을 직접 실행하는 bun run, Elysia·React·Next.js 등 템플릿에서 프로젝트를 생성하는 bun create, 제로 설정 프로젝트 초기화 도구 bun init을 다룹니다. 테스트 섹션에서는 describe(), test(), expect(), mock() 등 Jest 호환 API를 제공하는 bun test와 --watch 모드를 설명합니다.
번들러 섹션에서는 TypeScript/JSX를 트리 쉐이킹과 함께 브라우저 번들로 컴파일하는 bun build와 프로그래밍 방식의 코드 변환을 위한 Bun.Transpiler를 다룹니다. 설정 섹션에서는 패키지 레지스트리, 프리로드 스크립트, 기본 테스트 타임아웃을 설정하는 bunfig.toml을, 플러그인 섹션에서는 YAML·TOML 같은 커스텀 파일 포맷을 모듈로 가져올 수 있도록 빌드 시와 런타임 모두에서 동작하는 Bun.plugin()을 설명합니다. Node.js에서 Bun으로 마이그레이션하는 개발자, Elysia/Hono API를 개발하는 풀스택 엔지니어를 위한 자료입니다.
주요 기능
- Bun.serve()로 fetch 핸들러 기반 HTTP/WebSocket 서버 생성
- Bun.file()의 지연 로딩과 .text(), .json(), .arrayBuffer() 읽기 방법
- Bun.password로 bcrypt/argon2 비밀번호 해싱 및 검증
- Bun.CryptoHasher로 SHA-256, MD5 등 해시 알고리즘 적용과 hex 다이제스트 출력
- bun install, bun add, bun add -d를 이용한 npm 호환 패키지 관리
- Jest 호환 expect() 어서션과 --watch 모드를 지원하는 bun test
- --outdir 및 --target으로 browser/node/bun 번들을 생성하는 bun build
- bunfig.toml로 레지스트리, 프리로드 스크립트, 플러그인 설정
자주 묻는 질문
Bun이 Node.js와 다른 점은 무엇인가요?
Bun은 V8 대신 Safari의 JavaScriptCore 엔진 위에 Zig로 구현된 런타임입니다. Node.js, npm, 번들러(webpack/esbuild), 테스트 러너(Jest)를 단일 바이너리로 대체합니다. TypeScript와 JSX를 별도 설정 없이 네이티브로 지원하며, 직접 시스템 콜을 사용하는 파일 I/O(Bun.file, Bun.write)가 Node.js의 fs 모듈보다 상당히 빠릅니다.
Bun은 npm 패키지와 완전히 호환되나요?
Bun의 패키지 매니저는 package.json과 npm 레지스트리와 호환됩니다. 대부분의 npm 패키지가 수정 없이 동작합니다. fs, path, http, crypto 등 Node.js 내장 모듈도 구현되어 있어 Node.js 코드 대부분이 그대로 실행됩니다. 단, 네이티브 Node.js 애드온(.node 파일)이나 Node.js 내부 API에 의존하는 패키지는 호환 레이어가 필요할 수 있습니다.
bun test는 Jest와 어떻게 비교되나요?
bun test는 describe(), test(), it(), expect(), beforeEach(), afterEach(), jest.mock() 등 Jest API를 구현합니다. Bun이 TypeScript를 네이티브로 실행하므로 트랜스파일 오버헤드가 없고 테스트 파일을 병렬 처리해 Jest보다 훨씬 빠릅니다. Jest 전용 플러그인이나 커스텀 리포터는 호환되지 않을 수 있습니다. 일반적인 단위·통합 테스트 스위트에는 bun test로 충분합니다.
Bun.plugin()의 용도는 무엇인가요?
Bun.plugin()은 모듈 해석 파이프라인에 훅을 걸어 파일이 임포트되기 전에 변환할 수 있게 합니다. 필터 정규식으로 .yaml이나 .toml 같은 파일 확장자를 매핑하는 onLoad 핸들러를 등록하면, Bun이 해당 파일을 만날 때 핸들러를 호출하고 변환된 소스를 캐시해 실행합니다. webpack 로더나 Vite 플러그인과 달리 런타임(bun run)과 빌드 타임(bun build) 모두에서 동작합니다.
Bun.file()은 fs.readFile()과 어떻게 다른가요?
Bun.file()은 지연 BunFile 참조를 생성합니다. 생성 시점에는 I/O가 발생하지 않고, .text(), .json(), .arrayBuffer(), .stream() 을 호출할 때 실제로 읽습니다. 이는 Fetch API의 Response 객체와 유사한 방식입니다. 반면 fs.readFile()은 즉시 읽기를 시작합니다. BunFile은 내용을 읽지 않고도 .size와 .type으로 메타데이터에 접근할 수 있습니다.
bunfig.toml은 어떤 용도로 사용하나요?
bunfig.toml은 Bun의 설정 파일로, .npmrc와 package.json scripts의 역할을 합칩니다. [install] 섹션은 npm 레지스트리 URL과 스코프 패키지 레지스트리를 설정합니다. [run] 섹션은 모든 bun run 실행 전에 실행되는 프리로드 스크립트를 설정합니다(전역 mock이나 환경 설정에 유용). [test] 섹션은 테스트 타임아웃, 테스트용 프리로드, 커버리지 리포팅을 설정합니다.
Bun으로 webpack이나 Vite를 대체할 수 있나요?
bun build는 TypeScript, JSX, 트리 쉐이킹, 코드 분할을 지원하는 프로덕션 번들러로 webpack보다 훨씬 빠릅니다. 단, 2025년 초 기준으로 bun build에는 HMR(핫 모듈 교체)이 있는 내장 개발 서버가 없습니다. React나 Vue 같이 빠른 HMR에 의존하는 프론트엔드 프레임워크 개발에는 Vite가 더 적합합니다. Bun은 서버 사이드 코드와 CLI 도구 번들링에 탁월합니다.
모노레포에서 Bun 워크스페이스는 어떻게 사용하나요?
Bun은 루트 package.json의 workspaces 필드를 통해 npm 워크스페이스를 지원합니다. 루트에서 bun install을 실행하면 모든 워크스페이스 패키지를 설치하고 node_modules에 심볼릭 링크를 생성합니다. bun run --filter <워크스페이스명> <스크립트>로 특정 워크스페이스의 스크립트를 실행할 수 있습니다. npm/yarn 워크스페이스 스펙과 호환되므로 기존 모노레포는 락파일만 교체하면 전환됩니다.