ElysiaJS 1.0 실전 가이드: Bun 네이티브 프레임워크로 타입 안전 REST API 구축하기

import { Elysia, t } from 'elysia'
 
const app = new Elysia()
  .post('/users', ({ body }) => {
    // body는 { name: string; age: number } 타입으로 자동 추론
    // z.infer<...> 없음, 별도 타입 캐스팅 없음
    return { id: crypto.randomUUID(), ...body }
  }, {
    body: t.Object({
      name: t.String({ minLength: 1 }),
      age:  t.Number({ minimum: 0, maximum: 150 })
    })
  })
  .listen(3000)

import { Elysia } from 'elysia'
import { z } from 'zod'
 
const UserSchema = z.object({
  name:  z.string().min(1),
  email: z.string().email()
})
 
const app = new Elysia()
  .post('/users', ({ body }) => {
    // body는 z.infer<typeof UserSchema> 타입으로 추론됨
    return { id: crypto.randomUUID(), ...body }
  }, {
    body: UserSchema  // Zod 스키마를 직접 전달
  })

// 서버: src/index.ts
import { Elysia, t } from 'elysia'
 
const app = new Elysia()
  .get('/posts/:id', ({ params }) => ({
    id:      params.id,
    title:   'Hello Elysia',
    content: '...'
  }), {
    params: t.Object({ id: t.String() })
  })
  .post('/posts', ({ body }) => ({
    id: crypto.randomUUID(),
    ...body
  }), {
    body: t.Object({
      title:   t.String(),
      content: t.String()
    })
  })
  .listen(3000)
 
export type App = typeof app  // 런타임 값이 아닌 타입만 export

// 클라이언트: src/client.ts
import { treaty } from '@elysiajs/eden'
import type { App } from '../server/index'  // type import — 번들에 포함 안 됨
 
const api = treaty<App>('localhost:3000')
 
// /posts/:id → 경로 파라미터는 함수 인자로, HTTP 메서드는 체인 끝 메서드로
const { data, error } = await api.posts({ id: '1' }).get()
// data: { id: string; title: string; content: string } | null
 
const { data: created } = await api.posts.post({
  title:   '새 글',
  content: '내용'
})
// created: { id: string; title: string; content: string } | null

# Bun 설치 (미설치 시)
curl -fsSL https://bun.sh/install | bash
 
# 프로젝트 생성
bun create elysia my-api
cd my-api
 
# 공식 플러그인 설치
bun add @elysiajs/swagger @elysiajs/jwt @elysiajs/cors
 
# Eden Treaty: 단일 앱이라면
bun add @elysiajs/eden
 
# 모노레포에서 pnpm 워크스페이스를 쓴다면
pnpm --filter web add @elysiajs/eden

// src/routes/posts.ts
import { Elysia, t } from 'elysia'
 
export const postsRouter = new Elysia({ prefix: '/posts' })
  .get('/', () => ({
    posts: [] as { id: string; title: string; content: string }[]
  }))
  .post('/', ({ body }) => ({
    id: crypto.randomUUID(),
    ...body
  }), {
    body: t.Object({
      title:   t.String({ minLength: 1 }),
      content: t.String()
    })
  })
  .get('/:id', ({ params }) => ({
    id:      params.id,
    title:   '샘플 게시글',
    content: '내용'
  }), {
    params: t.Object({ id: t.String() })
  })

// src/index.ts
import { Elysia } from 'elysia'
import { cors } from '@elysiajs/cors'
import { swagger } from '@elysiajs/swagger'
import { postsRouter } from './routes/posts'
 
const app = new Elysia()
  .use(cors())
  .use(swagger({
    documentation: { info: { title: 'My API', version: '1.0.0' } }
  }))
  .use(postsRouter)
  .listen(3000)
 
console.log(`서버 시작: ${app.server?.hostname}:${app.server?.port}`)
 
export type App = typeof app

// src/plugins/auth.ts
import { Elysia } from 'elysia'
import { jwt } from '@elysiajs/jwt'
 
export const authPlugin = new Elysia({ name: 'auth' })
  .use(jwt({
    name:   'jwt',
    secret: process.env.JWT_SECRET!
  }))
  // derive: 토큰을 파싱해 user를 채우는 역할만 담당
  .derive(async ({ jwt, headers }) => {
    const token = headers.authorization?.replace('Bearer ', '')
    if (!token) return { user: null as { id: string; email: string } | null }
    const payload = await jwt.verify(token)
    return { user: (payload || null) as { id: string; email: string } | null }
  })
  // onBeforeHandle: user가 없으면 여기서 요청을 차단
  .onBeforeHandle(({ user, error }) => {
    if (!user) return error(401, { error: 'Unauthorized' })
  })

// src/routes/posts.ts (인증 포함 버전)
import { Elysia, t } from 'elysia'
import { authPlugin } from '../plugins/auth'
 
export const postsRouter = new Elysia({ prefix: '/posts' })
  .use(authPlugin)
  .get('/', ({ user }) => ({
    // authPlugin을 use()한 핸들러에서 user 타입이 자동 전파됨
    // onBeforeHandle 이후 TypeScript가 user를 자동으로 non-null로 좁히지 않을 수 있어
    // user! 가 필요한 경우가 있습니다
    posts: [] as { id: string; title: string; content: string }[],
    userId: user!.id
  }))
  .post('/', ({ body, user }) => ({
    id: crypto.randomUUID(),
    authorId: user!.id,
    ...body
  }), {
    body: t.Object({
      title:   t.String({ minLength: 1 }),
      content: t.String()
    })
  })
  .get('/:id', ({ params }) => ({
    id:      params.id,
    title:   '샘플 게시글',
    content: '내용'
  }), {
    params: t.Object({ id: t.String() })
  })

import { Elysia, t } from 'elysia'
 
class NotFoundError extends Error {
  constructor(resource: string) {
    super(`${resource}을(를) 찾을 수 없습니다`)
    this.name = 'NotFoundError'
  }
}
 
const app = new Elysia()
  .error({ NotFoundError })
  .onError(({ code, error, set }) => {
    if (code === 'NotFoundError') {
      set.status = 404
      return { error: error.message, code: 'NOT_FOUND' }
    }
    if (code === 'VALIDATION') {
      set.status = 422
      // error.message에 검증 실패 요약이 포함됩니다
      // TypeBox 기준 error.all로 필드별 에러 목록에 접근할 수도 있습니다
      return { error: '입력값이 올바르지 않습니다', details: error.message }
    }
    set.status = 500
    return { error: '서버 오류가 발생했습니다' }
  })
  .get('/posts/:id', ({ params }) => {
    if (params.id === '999') throw new NotFoundError('게시글')
    return { id: params.id, title: '게시글 제목' }
  }, {
    params: t.Object({ id: t.String() })
  })

// packages/api-client/src/index.ts (공유 패키지)
import { treaty } from '@elysiajs/eden'
import type { App } from '@my-project/api'
 
export const api = treaty<App>(
  process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000'
)

// apps/web/app/posts/page.tsx (서버 컴포넌트)
import { api } from '@my-project/api-client'
 
export default async function PostsPage() {
  const { data, error } = await api.posts.get()  // GET /posts
 
  if (error) return <div>오류: {error.value.error}</div>
 
  // data 타입이 완전히 추론됨 — 명시적 타입 어노테이션 불필요
  return (
    <ul>
      {data.posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

// apps/web/app/posts/new/CreatePostForm.tsx
'use client'
 
import { api } from '@my-project/api-client'
import { useState } from 'react'
 
export function CreatePostForm() {
  const [title, setTitle] = useState('')
 
  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault()
    const { data, error } = await api.posts.post({ title, content: '...' })
    // 서버에서 title 필드가 삭제되면 여기서 즉시 타입 에러 발생
    if (error) console.error(error.value)
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <input value={title} onChange={e => setTitle(e.target.value)} />
      <button type="submit">작성</button>
    </form>
  )
}

import { Elysia, t } from 'elysia'
import { drizzle } from 'drizzle-orm/bun-sqlite'
import { Database } from 'bun:sqlite'
import { posts } from './schema'
import { eq } from 'drizzle-orm'
 
const db = drizzle(new Database('app.db'))
 
export const postsRouter = new Elysia({ prefix: '/posts' })
  .decorate('db', db)  // 앱 수명 동안 변하지 않는 싱글턴 — 요청마다 재생성되지 않음
  .get('/:id', async ({ params, db, set }) => {
    const [post] = await db
      .select()
      .from(posts)
      .where(eq(posts.id, params.id))
      .limit(1)
 
    if (!post) {
      set.status = 404
      return { error: '게시글을 찾을 수 없습니다' }
    }
    return post  // Drizzle 반환 타입이 Eden Treaty 클라이언트까지 자동 전파
  }, {
    params: t.Object({ id: t.String() })
  })

// 이름 없으면 여러 라우터에서 use() 시 중복 등록
const authPlugin = new Elysia()
  .use(jwt({ name: 'jwt', secret: 'secret' }))
 
// name 지정으로 해결
const authPlugin = new Elysia({ name: 'auth' })
  .use(jwt({ name: 'jwt', secret: 'secret' }))

// 잘못된 예
await api.users[':id']({ id: '1' }).get()
 
// 올바른 예 — 경로 파라미터는 함수 인자로
await api.users({ id: '1' }).get()

// 잘못된 예 — derive는 속성 추가 용도, 요청 차단이 아님
.derive(async ({ headers, set }) => {
  if (!headers.authorization) {
    set.status = 401
    throw new Error('Unauthorized')  // 에러 핸들러 동작 보장 안 됨
  }
  return { user: /* ... */ }
})
 
// 올바른 예
.derive(async ({ jwt, headers }) => ({ user: /* 토큰 검증 결과 */ }))
.onBeforeHandle(({ user, error }) => {
  if (!user) return error(401, { error: 'Unauthorized' })
})