ElysiaJS 1.0 in Practice: Building a Type-Safe REST API with Bun's Native Framework

import { Elysia, t } from 'elysia'
 
const app = new Elysia()
  .post('/users', ({ body }) => {
    // body is automatically inferred as { name: string; age: number }
    // No z.infer<...>, no manual type casting
    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 is inferred as z.infer<typeof UserSchema>
    return { id: crypto.randomUUID(), ...body }
  }, {
    body: UserSchema  // pass Zod schema directly
  })

// Server: 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 type only, not a runtime value

// Client: src/client.ts
import { treaty } from '@elysiajs/eden'
import type { App } from '../server/index'  // type import — not included in bundle
 
const api = treaty<App>('localhost:3000')
 
// /posts/:id → path parameters as function arguments, HTTP method as the terminal chain method
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:   'New Post',
  content: 'Content'
})
// created: { id: string; title: string; content: string } | null

# Install Bun (if not installed)
curl -fsSL https://bun.sh/install | bash
 
# Create project
bun create elysia my-api
cd my-api
 
# Install official plugins
bun add @elysiajs/swagger @elysiajs/jwt @elysiajs/cors
 
# Eden Treaty: for a single app
bun add @elysiajs/eden
 
# For a monorepo with pnpm workspaces
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:   'Sample Post',
    content: '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(`Server started: ${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: responsible only for parsing the token and populating 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: blocks the request here if user is absent
  .onBeforeHandle(({ user, error }) => {
    if (!user) return error(401, { error: 'Unauthorized' })
  })

// src/routes/posts.ts (with authentication)
import { Elysia, t } from 'elysia'
import { authPlugin } from '../plugins/auth'
 
export const postsRouter = new Elysia({ prefix: '/posts' })
  .use(authPlugin)
  .get('/', ({ user }) => ({
    // user type is automatically propagated to handlers that use() authPlugin
    // TypeScript may not automatically narrow user to non-null after onBeforeHandle,
    // so user! may be necessary in some cases
    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:   'Sample Post',
    content: 'Content'
  }), {
    params: t.Object({ id: t.String() })
  })

import { Elysia, t } from 'elysia'
 
class NotFoundError extends Error {
  constructor(resource: string) {
    super(`${resource} not found`)
    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 contains a validation failure summary
      // With TypeBox, error.all can also be used to access per-field error lists
      return { error: 'Invalid input', details: error.message }
    }
    set.status = 500
    return { error: 'Internal server error' }
  })
  .get('/posts/:id', ({ params }) => {
    if (params.id === '999') throw new NotFoundError('Post')
    return { id: params.id, title: 'Post Title' }
  }, {
    params: t.Object({ id: t.String() })
  })

// packages/api-client/src/index.ts (shared package)
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 (Server Component)
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: {error.value.error}</div>
 
  // data type is fully inferred — no explicit type annotation needed
  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: '...' })
    // If the title field is removed on the server, a type error appears here immediately
    if (error) console.error(error.value)
  }
 
  return (
    <form onSubmit={handleSubmit}>
      <input value={title} onChange={e => setTitle(e.target.value)} />
      <button type="submit">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)  // singleton for the app's lifetime — not recreated per request
  .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: 'Post not found' }
    }
    return post  // Drizzle return type propagates automatically to the Eden Treaty client
  }, {
    params: t.Object({ id: t.String() })
  })

// Without a name, use()-ing across multiple routers causes duplicate registration
const authPlugin = new Elysia()
  .use(jwt({ name: 'jwt', secret: 'secret' }))
 
// Solved by specifying a name
const authPlugin = new Elysia({ name: 'auth' })
  .use(jwt({ name: 'jwt', secret: 'secret' }))

// Wrong
await api.users[':id']({ id: '1' }).get()
 
// Correct — path parameters as function arguments
await api.users({ id: '1' }).get()

// Wrong — derive is for adding properties, not blocking requests
.derive(async ({ headers, set }) => {
  if (!headers.authorization) {
    set.status = 401
    throw new Error('Unauthorized')  // error handler behavior not guaranteed
  }
  return { user: /* ... */ }
})
 
// Correct
.derive(async ({ jwt, headers }) => ({ user: /* token verification result */ }))
.onBeforeHandle(({ user, error }) => {
  if (!user) return error(401, { error: 'Unauthorized' })
})