Bun 완벽 가이드 — Node.js보다 빠른 JavaScript 런타임

Bun이란 무엇인가 — 왜 만들어졌나

설치 및 첫 프로젝트 셋업

Bun 설치 — macOS / Linux / Windows
# macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# Homebrew (macOS)
brew install oven-sh/bun/bun

# 버전 확인
bun --version
# 예시 출력: 1.2.4

# 새 프로젝트 초기화
bun init my-app
cd my-app

# 패키지 설치 (npm install과 동일)
bun install

# TypeScript 파일 직접 실행 (tsc 불필요)
bun run index.ts

# 개발 서버 (파일 변경 시 자동 재시작)
bun --hot run index.ts

Bun HTTP 서버 — 빌트인 Bun.serve() API
// index.ts
const server = Bun.serve({
  port: 3000,
  async fetch(req) {
    const url = new URL(req.url)

    if (url.pathname === '/') {
      return new Response('Hello from Bun!', {
        headers: { 'Content-Type': 'text/plain' }
      })
    }

    if (url.pathname === '/api/data') {
      // SQLite 쿼리 (빌트인 bun:sqlite)
      const db = new Database('app.db')
      const rows = db.query('SELECT * FROM items LIMIT 10').all()
      return Response.json(rows)
    }

    return new Response('Not Found', { status: 404 })
  },
  error(err) {
    return new Response(`Error: ${err.message}`, { status: 500 })
  }
})

console.log(`Server running at http://localhost:${server.port}`)

벤치마크 — Node.js, Deno와 실제 성능 비교

빌트인 기능 — 번들러, 테스트 러너, SQLite

bun build — 프론트엔드 번들링
# 단일 진입점 번들
bun build ./src/index.tsx --outdir ./dist --target browser --minify

# 라이브러리 빌드 (ESM + CJS)
bun build ./src/index.ts --outdir ./dist --target node --format esm
bun build ./src/index.ts --outdir ./dist --target node --format cjs

# 번들 결과 분석
bun build ./src/index.tsx --outdir ./dist --analyze

bun test — Jest 호환 테스트 작성
// math.test.ts
import { describe, test, expect, mock, beforeEach } from 'bun:test'

function add(a: number, b: number) { return a + b }
async function fetchUser(id: string) {
  const res = await fetch(`/api/users/${id}`)
  return res.json()
}

describe('add function', () => {
  test('두 수를 더한다', () => {
    expect(add(2, 3)).toBe(5)
  })

  test('음수를 처리한다', () => {
    expect(add(-1, 1)).toBe(0)
  })
})

describe('fetchUser', () => {
  beforeEach(() => {
    // fetch 목킹 (bun:test 빌트인)
    global.fetch = mock(() =>
      Promise.resolve(new Response(JSON.stringify({ id: '1', name: 'Alice' })))
    )
  })

  test('사용자 데이터를 반환한다', async () => {
    const user = await fetchUser('1')
    expect(user.name).toBe('Alice')
  })
})

Node.js 호환성 이슈 — 프로덕션 전에 확인할 것들

Bun을 언제 써야 하는가 — 실전 판단 기준