단계별 가이드: Node.js 21에서 Bun 1.2로 백엔드 API 마이그레이션

I’m happy to translate the article for you, but I need the full text you’d like translated. Could you please paste the content (or the portion you want translated) here? I’ll keep the source link at the top and preserve all formatting, markdown, and code blocks as requested.

Bun 1.2로 마이그레이션해야 하는 이유?

Bun 1.2는 속도를 위해 설계된 최신 JavaScript 런타임으로, 네이티브 TypeScript 지원, 내장 번들러, 테스트 러너, 패키지 관리자를 제공합니다. Node.js 21과 비교했을 때, Bun은 최대 3배 빠른 시작 시간, 낮은 메모리 사용량, 대부분의 Node.js API와의 원활한 호환성을 제공합니다. 백엔드 API의 경우, 이는 인프라 비용 절감, 응답 시간 단축, 도구 체인 단순화로 이어집니다.

마이그레이션 전 체크리스트

• 모든 의존성 감사 – bun audit를 사용하거나 Bun Node.js Compatibility 페이지를 참고하여 핵심 패키지의 지원 여부를 확인합니다.
• 프로젝트 백업 – 필요 시 되돌릴 수 있도록 별도의 Git 브랜치나 스냅샷을 생성합니다.
• Node‑특화 구현 식별 – __dirname, __filename 또는 커스텀 코어 모듈 폴리필 사용 여부를 확인하고, 필요에 따라 조정합니다.

Bun 설치

curl -fsSL https://bun.sh/install | bash

설치 확인:

bun --version
# Should output 1.2.x

프로젝트 구성

기존 Node.js 21 프로젝트 디렉터리로 이동합니다. bunfig.toml 파일이 없으면 Bun의 동작을 사용자 정의하기 위해 하나 생성합니다:

# bunfig.toml
[install]
registry = "https://registry.npmjs.org"

[test]
preload = ["./test/setup.ts"]

package.json을 업데이트하여 프로젝트 유형을 ESM으로 설정합니다 (Bun은 CommonJS도 동작하지만, 호환성을 위해 ESM이 권장됩니다):

{
  "type": "module",
  "scripts": {
    "start": "bun run src/index.ts",
    "test": "bun test"
  }
}

npm install을 Bun의 내장 패키지 매니저로 교체합니다:

bun install

Bun은 기존 package.json 및 잠금 파일(package-lock.json / yarn.lock)을 읽고 바이너리 bun.lockb를 생성합니다. 의존성에서 오류가 발생하면 Bun과 호환되는 대안을 찾거나 최신 버전으로 업데이트하십시오.

Code adjustments

Switch from CommonJS to ESM

// Before (CommonJS)
const express = require("express");
const { PORT } = require("./config");

// After (ESM)
import express from "express";
import { PORT } from "./config.js"; // note the .js extension

Replace __dirname / __filename

// Before (Node.js CJS)
console.log(__dirname);

// After (Bun ESM)
import { fileURLToPath } from "url";
import { dirname } from "path";

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

Environment variables

// Bun’s alias (slightly faster)
const port = Bun.env.PORT || 3000;

Optional: Use Bun‑optimized frameworks

Express를 사용하고 있다면 그대로 사용할 수 있지만, 추가 성능을 위해 Elysia와 같은 Bun 네이티브 프레임워크로 전환할 수 있습니다:

import { Elysia } from "elysia";

const app = new Elysia()
  .get("/", () => "Hello from Bun 1.2!")
  .listen(3000, () => {
    console.log("Server running on port 3000");
  });

ORMs

Prisma, Drizzle 또는 기타 ORM을 사용할 경우, 데이터베이스 연결을 Bun 호환 드라이버(예: SQLite용 bun:sqlite 또는 Bun에서 동작하는 표준 PostgreSQL/MySQL 드라이버)로 업데이트하세요.

Bun으로 테스트하기

Bun은 Jest 구문과 호환되는 내장 테스트 러너를 포함합니다.

# 모든 테스트 실행
bun test

# 특정 테스트 파일 실행
bun test src/__tests__/api.test.ts

API 엔드포인트를 수동으로 검증하세요:

curl http://localhost:3000/api/users

회귀가 없음을 확인하기 위해 전체 통합 테스트 스위트를 실행하세요.

Replace Node‑specific APIs (optional but recommended)

• Use Bun.serve() for HTTP servers instead of http.createServer() when not using a framework.
• Use Bun.file() and Bun.write() for file operations instead of the fs module polyfills.
• Remove unnecessary Node shims (e.g., node-fetch is redundant because Bun has a built‑in fetch API).

Node‑특정 API 교체 (선택 사항이지만 권장)

• 프레임워크를 사용하지 않을 때 http.createServer() 대신 Bun.serve()를 사용하여 HTTP 서버를 구현합니다.
• 파일 작업은 fs 모듈 폴리필 대신 Bun.file() 및 Bun.write()를 사용합니다.
• 불필요한 Node shim을 제거합니다(예: Bun에 내장된 fetch API가 있으므로 node-fetch는 중복됩니다).

Bun 1.2 배포

Docker

FROM oven/bun:1.2
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install
COPY . .
EXPOSE 3000
CMD ["bun", "run", "src/index.ts"]

클라우드 제공업체

Bun은 Fly.io, Railway, Render와 같은 플랫폼에서 지원됩니다. 각 제공업체의 문서를 따라 Bun 런타임을 활성화하세요.

CI/CD

빌드 및 테스트 단계를 실행하기 전에 Node.js 21 대신 Bun을 설치하도록 CI 파이프라인(GitHub Actions, GitLab CI 등)을 업데이트하세요.

피해야 할 일반적인 함정

• package.json에 "type": "module"을 설정하지 않고 ESM으로 마이그레이션하기.
• 아직 Bun에서 지원되지 않는 Node 코어 모듈 사용 (먼저 호환성 문서를 확인).
• 충분한 테스트를 건너뛰기 – 프로덕션에 배포하기 전에 반드시 스테이징 환경에서 검증할 것.

Node.js 21에서 Bun 1.2로 마이그레이션하는 것은 대부분의 백엔드 API에 대해 코드 변경이 최소화되어 비교적 간단합니다. 더 빠른 성능, 간편한 도구 체인, 그리고 Bun의 성장 중인 네이티브 툴 생태계에 접근할 수 있습니다. 먼저 중요도가 낮은 작은 API로 과정을 테스트한 뒤, 워크플로에 익숙해지면 더 큰 서비스로 확대해 나가세요.