ElysiaJS 실전 튜토리얼 — Bun 기반 TypeScript API 서버, JWT 인증, Swagger 문서화, Docker 배포

프로젝트 초기화 및 ElysiaJS 설치
# Bun 설치 확인
bun --version

# 새 프로젝트 생성
mkdir elysia-api && cd elysia-api
bun init -y

# ElysiaJS 및 핵심 플러그인 설치
bun add elysia @elysiajs/jwt @elysiajs/swagger @elysiajs/cors
bun add drizzle-orm drizzle-kit @libsql/client
bun add --dev @types/bun

package.json scripts 설정
{
  "scripts": {
    "dev": "bun run --watch src/index.ts",
    "start": "bun run src/index.ts",
    "db:generate": "drizzle-kit generate",
    "db:migrate": "bun run src/db/migrate.ts"
  }
}

src/index.ts — 기본 라우팅 구조
import { Elysia, t } from 'elysia'

const app = new Elysia()
  .get('/', () => ({ message: 'ElysiaJS API' }))

  // 경로 파라미터 — :id는 string 타입으로 추론
  .get('/users/:id', ({ params }) => {
    return { userId: params.id }
  })

  // 요청 바디 스키마 정의 (t.Object)
  .post('/users', ({ body }) => {
    return { created: true, user: body }
  }, {
    body: t.Object({
      name: t.String(),
      email: t.String({ format: 'email' }),
      age: t.Optional(t.Number())
    })
  })

  // 쿼리스트링 검증
  .get('/search', ({ query }) => {
    return { q: query.q, page: query.page }
  }, {
    query: t.Object({
      q: t.String(),
      page: t.Optional(t.Number({ minimum: 1, default: 1 }))
    })
  })

  .listen(3000)

console.log('Server running at http://localhost:3000')

src/plugins/logger.ts — 요청 로거 플러그인
import { Elysia } from 'elysia'

export const loggerPlugin = new Elysia({ name: 'logger' })
  .onRequest(({ request }) => {
    const url = new URL(request.url)
    console.log('[' + new Date().toISOString() + '] ' + request.method + ' ' + url.pathname)
  })
  .onError(({ error, code }) => {
    console.error('[ERROR ' + code + ']', error.message)
  })

src/routes/users.ts — 라우트 모듈 분리
import { Elysia, t } from 'elysia'

const users: { id: number; name: string; email: string }[] = []
let nextId = 1

export const usersRoute = new Elysia({ prefix: '/users' })
  .get('/', () => users)
  .get('/:id', ({ params, error }) => {
    const user = users.find(u => u.id === Number(params.id))
    if (!user) return error(404, { message: 'User not found' })
    return user
  })
  .post('/', ({ body }) => {
    const user = { id: nextId++, ...body }
    users.push(user)
    return { status: 201, user }
  }, {
    body: t.Object({
      name: t.String({ minLength: 1 }),
      email: t.String({ format: 'email' })
    })
  })
  .delete('/:id', ({ params, error }) => {
    const idx = users.findIndex(u => u.id === Number(params.id))
    if (idx === -1) return error(404, { message: 'User not found' })
    users.splice(idx, 1)
    return { deleted: true }
  })

src/routes/auth.ts — JWT 인증 라우트
import { Elysia, t } from 'elysia'
import { jwt } from '@elysiajs/jwt'

const JWT_SECRET = process.env.JWT_SECRET ?? 'change-me-in-production'

export const authRoute = new Elysia({ prefix: '/auth' })
  .use(
    jwt({
      name: 'jwt',
      secret: JWT_SECRET,
      exp: '7d'
    })
  )
  // 로그인 — 토큰 발급
  .post('/login', async ({ body, jwt: jwtCtx, error }) => {
    // 실제 환경에서는 DB 조회 + bcrypt 비교
    if (body.email !== 'admin@example.com' || body.password !== 'password') {
      return error(401, { message: 'Invalid credentials' })
    }
    const token = await jwtCtx.sign({ sub: '1', email: body.email, role: 'admin' })
    return { token }
  }, {
    body: t.Object({
      email: t.String({ format: 'email' }),
      password: t.String({ minLength: 6 })
    })
  })
  // 내 정보 조회 — 토큰 검증
  .get('/me', async ({ headers, jwt: jwtCtx, error }) => {
    const authHeader = headers['authorization']
    if (!authHeader?.startsWith('Bearer ')) {
      return error(401, { message: 'Unauthorized' })
    }
    const token = authHeader.slice(7)
    const payload = await jwtCtx.verify(token)
    if (!payload) return error(401, { message: 'Invalid token' })
    return { user: payload }
  })

src/index.ts — Swagger 플러그인 통합
import { Elysia } from 'elysia'
import { swagger } from '@elysiajs/swagger'
import { cors } from '@elysiajs/cors'
import { loggerPlugin } from './plugins/logger'
import { usersRoute } from './routes/users'
import { authRoute } from './routes/auth'

const app = new Elysia()
  .use(cors({
    origin: process.env.ALLOWED_ORIGIN ?? '*',
    methods: ['GET', 'POST', 'PUT', 'DELETE']
  }))
  // Swagger UI — /swagger 경로에서 확인 가능
  .use(swagger({
    documentation: {
      info: {
        title: 'ElysiaJS API',
        version: '1.0.0',
        description: 'Bun 기반 TypeScript REST API'
      },
      tags: [
        { name: 'auth', description: '인증 관련 엔드포인트' },
        { name: 'users', description: '사용자 CRUD' }
      ]
    }
  }))
  .use(loggerPlugin)
  .use(authRoute)
  .use(usersRoute)
  .listen(3000)

console.log('Server running at http://localhost:3000')
console.log('Swagger UI at http://localhost:3000/swagger')

Dockerfile — 멀티스테이지 빌드
# 빌드 스테이지
FROM oven/bun:1 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .

# 프로덕션 스테이지
FROM oven/bun:1-slim AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/src ./src
COPY --from=builder /app/package.json ./
EXPOSE 3000
CMD ["bun", "run", "src/index.ts"]

docker-compose.yml — 로컬 개발 환경
services:
  api:
    build: .
    ports:
      - '3000:3000'
    environment:
      - JWT_SECRET=your-secret-here
      - ALLOWED_ORIGIN=http://localhost:5173
    volumes:
      - ./src:/app/src
    restart: unless-stopped

Docker 빌드 및 실행
# 이미지 빌드
docker build -t elysia-api .

# 컨테이너 실행
docker run -p 3000:3000 -e JWT_SECRET=$(openssl rand -hex 32) elysia-api

# docker-compose 사용 시
docker compose up -d