Bun을 패키지 매니저로만 쓸 때의 현실적 주의점

Bun은 런타임 + 번들러 + 패키지 매니저를 모두 포함하지만, 많은 팀이 우선 패키지 매니저로만 도입합니다. npm install보다 압도적으로 빠르기 때문입니다. 그러나 Node 런타임 위에 돌아가는 프로젝트에서 Bun 패키지 매니저를 쓸 때 알아둘 점이 몇 가지 있습니다.

1. 왜 빠른가

Bun은 Zig로 작성된 네이티브 바이너리이고, 의존성 설치 시 다음을 병렬화합니다.

• HTTP 요청 (다중 스트림)
• tarball 풀기
• 파일 시스템 쓰기 (linker는 hardlink)

결과: 같은 의존성 트리를 npm 30초 → Bun 5초 수준으로 설치합니다. 큰 프로젝트일수록 차이가 큽니다.

2. lockfile 형식

Bun은 자체 binary lockfile (bun.lockb)을 만듭니다.

• npm/yarn/pnpm과 호환되지 않습니다.
• 텍스트가 아니라 git diff에서 변경 내용을 볼 수 없습니다.
• bun pm migrate로 package-lock.json에서 변환 가능.

다른 팀원이 npm을 쓰면 lockfile이 두 개로 갈라져 의존성 트리가 어긋날 수 있습니다. 팀 차원에서 한 도구로 통일이 권장됩니다.

3. CI에서 사용하기

1# .github/workflows/ci.yml
2- uses: oven-sh/setup-bun@v2
3  with:
4    bun-version: latest
5
6- run: bun install --frozen-lockfile
7- run: bun run build

--frozen-lockfile은 lockfile과 package.json이 일치하지 않으면 설치를 막습니다. CI에서 의존성 변화를 명시적으로 관리합니다.

4. Node 런타임에서 Bun 설치 의존성

Bun이 설치한 의존성은 Node로도 잘 실행됩니다. 단, 몇 가지 함정이 있습니다.

• postinstall 스크립트 — Bun은 일부 native postinstall을 다르게 처리합니다. sharp, node-canvas 같은 native 모듈은 가끔 Bun에서 빌드되지 않은 채 설치되어 Node 런타임에서 깨집니다.
• peer dependencies — Bun은 peer 의존성에 대한 경고를 npm/pnpm보다 덜 자세히 출력합니다. 명시적인 peerDeps 충돌이 묻힐 수 있습니다.
• workspace 의존성 — workspace:* 프로토콜은 지원하지만, npm publish 시 처리가 도구별로 미세하게 다릅니다.

5. monorepo 사용

Bun은 workspace를 지원합니다.

1// package.json
2{
3  "workspaces": ["apps/*", "packages/*"]
4}

1bun install
2bun --filter '@app/web' run dev

다만 pnpm에 비해 모노레포 기능(catalog, hoisting 옵션 등)이 적습니다. 단순한 모노레포에서는 충분, 복잡한 곳에서는 pnpm이 안전합니다.

6. 점진적 도입 전략

1# 1) 기존 lockfile에서 변환
2bun pm migrate
3
4# 2) lockfile 두 개 잠시 공존 (CI에서 npm 사용 유지)
5# 3) 안정적이면 npm lockfile 삭제 + CI도 Bun 전환

작은 프로젝트는 한 번에 옮겨도 되지만, 큰 프로젝트는 한두 주 같이 두면서 차이를 관찰합니다.

7. 정리

항목	평가
설치 속도	매우 빠름 (npm 대비 5-10x)
lockfile	binary, diff 안 됨
native postinstall	일부 케이스 주의
monorepo	단순한 곳에 OK, 복잡한 곳은 pnpm
CI 통합	setup-bun 액션으로 쉬움

런타임을 Node로 유지하면서 패키지 매니저만 Bun으로 바꿔도 설치 시간이 크게 줄어듭니다. 도입 비용은 낮지만, 팀이 모두 같은 도구를 써야 효과가 있습니다.

참고: Bun 공식 문서 — Package Manager / setup-bun GitHub Action.