Elysia.js + Bun으로 서버-클라이언트 타입을 한 번에 묶는 법

import { Elysia, t } from 'elysia'
 
const app = new Elysia()
  .get('/users/:id', ({ params }) => {
    return { id: params.id, name: 'Alice' }
  }, {
    params: t.Object({
      id: t.String()
    }),
    response: t.Object({
      id: t.String(),
      name: t.String()
    })
  })

// 서버 (apps/api/src/index.ts)
import { Elysia, t } from 'elysia'
 
const app = new Elysia()
  .post('/login', ({ body }) => ({
    token: `jwt_${body.username}`
  }), {
    body: t.Object({
      username: t.String(),
      password: t.String()
    }),
    response: t.Object({
      token: t.String()
    })
  })
  .listen(3000)
 
export type App = typeof app  // ← 이게 핵심

// 클라이언트 (apps/web/src/lib/api.ts)
import { treaty } from '@elysiajs/eden'
import type { App } from '../../api/src/index'  // 타입만 import
 
const client = treaty<App>('http://localhost:3000')
 
const { data, error } = await client.login.post({
  username: 'alice',
  password: 'secret'
})
 
// data.token은 string으로 추론됨
// data.nonexistent ← TypeScript 에러 발생

// GET /users/:id → client.users({ id: '123' }).get()
const { data } = await client.users({ id: '123' }).get()
// data의 타입은 서버 response 스키마에서 자동 추론

my-app/
├── apps/
│   ├── api/          ← Elysia 서버
│   │   ├── src/
│   │   │   └── index.ts
│   │   └── package.json
│   └── web/          ← Next.js / React
│       ├── src/
│       │   └── lib/api.ts
│       └── package.json
├── package.json      ← pnpm workspaces 루트
└── pnpm-workspace.yaml

# pnpm-workspace.yaml
packages:
  - 'apps/*'

# apps/api 디렉토리에서
bun add elysia @elysiajs/openapi @elysiajs/cors @elysiajs/jwt @elysiajs/bearer
 
# apps/web 디렉토리에서
bun add @elysiajs/eden

// apps/api/src/index.ts
import { Elysia, t } from 'elysia'
import { openapi } from '@elysiajs/openapi'
import { cors } from '@elysiajs/cors'
 
// 실제 프로젝트에서는 DB 조회로 교체
const USERS = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' },
]
 
const userRoutes = new Elysia({ prefix: '/users' })
  .get('/', () => USERS, {
    detail: { summary: '전체 사용자 목록 조회', tags: ['Users'] },
    response: t.Array(t.Object({
      id: t.String(),
      name: t.String(),
      email: t.String()
    }))
  })
  .get('/:id', ({ params, error }) => {
    const user = USERS.find(u => u.id === params.id)
    if (!user) return error(404, { message: '사용자를 찾을 수 없습니다' })
    return user
  }, {
    params: t.Object({ id: t.String() }),
    response: {
      200: t.Object({ id: t.String(), name: t.String(), email: t.String() }),
      404: t.Object({ message: t.String() })
    },
    detail: { summary: '특정 사용자 조회', tags: ['Users'] }
  })
  .post('/', ({ body }) => ({
    id: crypto.randomUUID(),
    ...body
  }), {
    body: t.Object({
      name: t.String({ minLength: 1 }),
      email: t.String({ format: 'email' })
    }),
    detail: { summary: '사용자 생성', tags: ['Users'] }
  })
 
const app = new Elysia()
  .use(cors())
  .use(openapi({
    documentation: {
      info: {
        title: 'My API',
        version: '1.0.0',
        description: 'Elysia.js로 구성된 타입 안전 API'
      }
    }
  }))
  .use(userRoutes)
  .listen(3000)
 
console.log('서버 실행 중: http://localhost:3000')
console.log('API 문서: http://localhost:3000/openapi')
 
export type App = typeof app

bun run src/index.ts
 
# 다른 터미널에서
curl http://localhost:3000/openapi/json | jq '.paths'

import { db } from './db'
import { products } from './schema'
 
app.get('/products', async () => {
  return db.select().from(products)
}, {
  // Drizzle 반환 타입은 TypeScript 컴파일 타임에만 추론됩니다.
  // OpenAPI 문서에 반영하려면 response 스키마를 별도로 명시해야 합니다.
  response: t.Array(t.Object({
    id: t.Number(),
    name: t.String(),
    price: t.Number()
  }))
})

// apps/web/src/lib/api.ts
import { treaty } from '@elysiajs/eden'
import type { App } from '../../api/src/index'
 
const baseUrl = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000'
 
export const api = treaty<App>(baseUrl)

// apps/web/src/components/UserList.tsx (Next.js Server Component)
import { api } from '@/lib/api'
 
export async function UserList() {
  const { data, error } = await api.users.get()
 
  if (error) {
    return <p>에러: {error.value.message}</p>
  }
 
  return (
    <ul>
      {data.map(user => (
        // user.id, user.name, user.email 모두 타입 추론됨
        <li key={user.id}>{user.name} — {user.email}</li>
      ))}
    </ul>
  )
}

// apps/web/src/components/UserDetail.tsx
import { api } from '@/lib/api'
 
export async function UserDetail({ id }: { id: string }) {
  // GET /users/:id → api.users({ id }).get()
  const { data, error } = await api.users({ id }).get()
 
  if (error?.status === 404) {
    return <p>{error.value.message}</p>
  }
 
  if (error) return <p>알 수 없는 오류</p>
 
  return <div>{data.name} ({data.email})</div>
}

// apps/web/src/components/CreateUserForm.tsx (Client Component)
'use client'
import { api } from '@/lib/api'
 
export function CreateUserForm() {
  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
    e.preventDefault()
    const formData = new FormData(e.currentTarget)
 
    const { data, error } = await api.users.post({
      // formData.get()은 FormDataEntryValue | null을 반환합니다.
      // required 속성이 있어도 TypeScript는 이를 보장하지 못하므로
      // null 처리를 명시하는 것이 안전합니다.
      name: formData.get('name')?.toString() ?? '',
      email: formData.get('email')?.toString() ?? ''
    })
 
    if (error) {
      console.error(error.value)
      return
    }
 
    console.log('생성됨:', data.id)
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <input name="name" placeholder="이름" required />
      <input name="email" type="email" placeholder="이메일" required />
      <button type="submit">생성</button>
    </form>
  )
}

bun add @ap0nia/eden-query @tanstack/react-query

// apps/web/src/lib/eden-query.ts
import { createEdenTreatyReactQuery } from '@ap0nia/eden-query/react'
import type { App } from '../../api/src/index'
 
export const eden = createEdenTreatyReactQuery<App>()
export const edenClient = eden.createClient({
  links: [
    eden.httpLink({ domain: 'http://localhost:3000' })
  ]
})

// apps/web/src/app/providers.tsx
'use client'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { eden, edenClient } from '@/lib/eden-query'
 
const queryClient = new QueryClient()
 
export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <eden.Provider client={edenClient} queryClient={queryClient}>
        {children}
      </eden.Provider>
    </QueryClientProvider>
  )
}

// apps/web/src/components/UserListWithQuery.tsx
'use client'
import { eden } from '@/lib/eden-query'
 
export function UserListWithQuery() {
  const { data, isLoading } = eden.users.get.useQuery()
  const createUser = eden.users.post.useMutation()
 
  if (isLoading) return <p>로딩 중...</p>
 
  return (
    <>
      <ul>
        {data?.map(user => (
          <li key={user.id}>{user.name}</li>
        ))}
      </ul>
      <button
        onClick={() => createUser.mutate({ name: 'Charlie', email: 'charlie@example.com' })}
      >
        사용자 추가
      </button>
    </>
  )
}

// apps/api/src/middleware/auth.ts
import { Elysia } from 'elysia'
import { jwt } from '@elysiajs/jwt'
import { bearer } from '@elysiajs/bearer'
 
export const authMiddleware = new Elysia({ name: 'auth' })
  .use(jwt({ name: 'jwt', secret: process.env.JWT_SECRET! }))
  .use(bearer())
  .derive(async ({ jwt, bearer, error }) => {
    const payload = await jwt.verify(bearer)
    if (!payload) return error(401, { message: '인증 실패' })
    return { user: payload as { id: string; email: string } }
  })

// apps/api/src/index.ts
import { Elysia, t } from 'elysia'
import { jwt } from '@elysiajs/jwt'
import { authMiddleware } from './middleware/auth'
 
// 로그인 엔드포인트 — JWT 검증 미들웨어 적용 안 함
const authRoutes = new Elysia({ prefix: '/auth' })
  .use(jwt({ name: 'jwt', secret: process.env.JWT_SECRET! }))
  .post('/login', async ({ body, jwt, error }) => {
    // 실제 프로젝트에서는 DB에서 사용자 확인 필요
    if (body.username !== 'alice' || body.password !== 'secret') {
      return error(401, { message: '자격증명 오류' })
    }
    const token = await jwt.sign({ id: '1', email: 'alice@example.com' })
    return { token }
  }, {
    body: t.Object({ username: t.String(), password: t.String() })
  })
 
// 보호된 라우트 — JWT 검증 미들웨어 적용
const protectedRoutes = new Elysia({ prefix: '/me' })
  .use(authMiddleware)
  .get('/', ({ user }) => ({ id: user.id, email: user.email }))
  // user.id, user.email은 authMiddleware의 derive 타입에서 자동 추론됨
 
const app = new Elysia()
  .use(authRoutes)
  .use(protectedRoutes)
  .listen(3000)
 
export type App = typeof app

const app = new Elysia()
  // derive: 모든 요청에서 헤더를 파싱해 컨텍스트 추가
  .derive(({ headers }) => ({
    requestId: headers['x-request-id'] ?? crypto.randomUUID()
  }))
  // resolve: 핸들러 직전에 타이머 시작
  .resolve(async () => ({
    startTime: Date.now()
  }))
  .get('/ping', ({ requestId, startTime }) => ({
    requestId,
    elapsed: Date.now() - startTime
  }))

// ❌ 플러그인을 메인 앱에 합성하지 않고 별도로 내보내면
//    Eden이 이 타입을 볼 수 없음
const authPlugin = new Elysia()
  .derive(({ headers }) => ({ user: parseUser(headers) }))
 
export { authPlugin }  // App 타입에 포함 안 됨
 
// ✅ 반드시 메인 앱에서 .use()로 합성해야 함
const app = new Elysia()
  .use(authPlugin)  // authPlugin 타입이 app 타입에 포함됨
  .get('/me', ({ user }) => user)  // user 타입 정상 추론
 
export type App = typeof app  // Eden이 user 타입을 볼 수 있음

bun create elysia my-app
cd my-app && bun dev
# http://localhost:3000 확인