Elysia Backend Development

Build fast, type-safe APIs with Elysia + Bun.

Mandatory Guidelines

[!IMPORTANT] All work in this skill MUST adhere to rules em .agent/rules/ — clean-code, code-style, javascript-only, naming-conventions.

Quick Reference

import { Elysia, t } from 'elysia'

const app = new Elysia()
    .get('/', () => 'Hello Elysia')
    .post('/users', ({ body }) => createUser(body), {
        body: t.Object({
            name: t.String(),
            email: t.String({ format: 'email' }),
        }),
    })
    .listen(3000)

Content Map

File	Description	When to Read
elysia-basics.md	Setup, routes, handlers, context	Starting new project
elysia-plugins.md	Plugins, guards, modular design	Organizing code
elysia-validation.md	TypeBox validation (body, query, params)	Input validation
elysia-lifecycle.md	Hooks (onBeforeHandle, onError, etc.)	Middleware, auth checks
elysia-patterns.md	REST patterns, responses, pagination	API design

Project Structure

src/
├── index.js           # Entry point
├── routes/
│   ├── index.js       # Route aggregator
│   ├── users.js       # User routes plugin
│   └── posts.js       # Post routes plugin
├── services/
│   ├── user.js        # Business logic
│   └── post.js
├── database/
│   ├── db.js          # Drizzle connection
│   ├── schema.js      # Drizzle schema
│   └── migrations/
└── middleware/
    ├── auth.js        # Auth middleware
    └── logger.js      # Request logging

Dependencies

Pacote	Versão	Descrição
bun	latest	Runtime
elysia	latest	Framework HTTP
bun:sqlite	builtin	SQLite driver
drizzle-orm	latest	ORM
bun:s3	latest	S3/R2 Storage

Core Patterns

Route Plugin

// routes/users.js
import { Elysia, t } from 'elysia'
import { getUserById, createUser } from '../services/user'

export const userRoutes = new Elysia({ prefix: '/users' })
    .get('/', () => getAllUsers())
    .get('/:id', ({ params }) => getUserById(params.id))
    .post('/', ({ body }) => createUser(body), {
        body: t.Object({
            name: t.String({ minLength: 1 }),
            email: t.String({ format: 'email' }),
        }),
    })

Main App

// index.js
import { Elysia } from 'elysia'
import { userRoutes } from './routes/users'
import { postRoutes } from './routes/posts'

const app = new Elysia()
    .onError(({ error, set }) => {
        console.error(error)
        set.status = 500
        return { error: 'Internal Server Error' }
    })
    .use(userRoutes)
    .use(postRoutes)
    .listen(3000)

console.log(`Server running at ${app.server?.url}`)

Related Skills

Need	Skill
Authentication	@[.agent/skills/riligar-dev-auth-elysia]
database	@[.agent/skills/riligar-dev-database]
Infrastructure	@[.agent/skills/riligar-infra-fly]

Decision Checklist

Before building an API:

• Defined route structure and prefixes?
• Planned validation for all inputs?
• Error handling configured?
• Auth middleware needed? → Use riligar-dev-auth-elysia
• database connection setup? → Use riligar-dev-database

Anti-Patterns

Don't	Do
Put business logic in handlers	Extract to services/
Skip input validation	Use TypeBox (t.Object)
Ignore error handling	Use onError lifecycle
Create monolithic files	Split into plugins
Use verbs in routes (/getUser)	Use nouns (/users/:id)