/api-framework-elysia

name: api-framework-elysia
description: Bun-native HTTP framework — routing, TypeBox validation, Eden Treaty, plugins, lifecycle hooks

API Development with Elysia

> **Quick Guide:** Elysia is a Bun-native HTTP framework with end-to-end type safety. Use method chaining (not separate statements) so TypeScript infers the full route tree. Import `t` from `elysia` for TypeBox validation. Export the app type (`export type App = typeof app`) for Eden Treaty clients. Use `status()` (not the deprecated `error()` function) for error responses with type narrowing.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST use method chaining on the Elysia instance -- separate `.get()` calls break type inference for Eden Treaty)**

**(You MUST use `status()` for error responses -- `error()` is deprecated since 1.3, prefer `status()`)**

**(You MUST export the app type (`export type App = typeof app`) for Eden Treaty client generation)**

</critical_requirements>

---

**Auto-detection:** Elysia, elysia, ElysiaJS, Eden Treaty, @elysiajs/eden, @elysiajs/openapi, t.Object, t.String, t.Number, t.File, TypeBox, .derive(), .decorate(), .guard(), .macro(), .ws(), onBeforeHandle, onAfterHandle, onRequest, treaty, bun:test

**When to use:**

• Building APIs on Bun runtime with end-to-end type safety
• Need RPC-style client with zero code generation (Eden Treaty)
• TypeBox validation with AOT compilation (~18x faster than Zod on Bun)
• Plugin-based architecture with automatic type propagation
• WebSocket support with schema validation

**When NOT to use:**

• Deploying to Node.js-only environments without Bun (use a Node-first framework)
• Need OpenAPI-first design with `createRoute` patterns (other frameworks with Zod-OpenAPI integration are more mature for this)
• Team already committed to Express/Fastify ecosystem

**Key patterns covered:**

• Route definitions with method chaining and TypeBox validation
• Plugin architecture with `.use()`, `.derive()`, `.decorate()`, `.macro()`
• Scoping rules (local, scoped, global) and `.guard()`
• End-to-end type safety with Eden Treaty
• Lifecycle hooks (onRequest, onBeforeHandle, onAfterHandle, onError)
• Error handling with custom error classes and `status()`
• WebSocket with schema validation
• Testing with `bun:test` and `.handle()` or Eden Treaty

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Route setup, method chaining, validation, plugins
• [examples/eden-treaty.md](examples/eden-treaty.md) - End-to-end type-safe client
• [examples/lifecycle-errors.md](examples/lifecycle-errors.md) - Lifecycle hooks, error handling, custom errors
• [examples/websocket-testing.md](examples/websocket-testing.md) - WebSocket patterns and unit testing
• [reference.md](reference.md) - Decision frameworks, anti-patterns, production checklist

---

<philosophy>

Philosophy

**Method chaining IS the type system.** Elysia infers the entire route tree through chained calls. Breaking the chain (separate `app.get()` statements) loses type information for Eden Treaty clients. This is the single most important architectural constraint.

**TypeBox over Zod for Bun.** While Elysia 1.4+ supports Standard Schema (Zod, Valibot, etc.), TypeBox (`t` from `elysia`) uses AOT compilation inside Bun for ~18x faster validation. Use TypeBox as default; use Zod only when sharing schemas with a non-Bun codebase.

**Plugins are Elysia instances.** Every `new Elysia()` is a plugin. There is no separate plugin API -- you compose by chaining `.use()`. The `name` property deduplicates plugins across the tree.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Route Setup with Method Chaining

Chain route definitions on the Elysia instance. Each `.get()`, `.post()`, etc. returns the instance with updated type information.

import { Elysia, t } from "elysia";

const app = new Elysia()
  .get("/", () => "hello")
  .get("/user/:id", ({ params: { id } }) => id, {
    params: t.Object({
      id: t.Number(),
    }),
  })
  .post("/user", ({ body }) => body, {
    body: t.Object({
      name: t.String(),
      email: t.String({ format: "email" }),
    }),
  })
  .listen(3000);

export type App = typeof app;

**Why good:** method chaining preserves type inference across the entire route tree, `export type App` enables Eden Treaty, TypeBox validates at runtime with AOT compilation

See [examples/core.md](examples/core.md) for complete route setup with modular plugins.

---

Pattern 2: Plugin Architecture

Every Elysia instance is a plugin. Use `.use()` to compose, `name` to deduplicate.

import { Elysia } from "elysia";

const userPlugin = new Elysia({ name: "user", prefix: "/user" })
  .get("/", () => "list users")
  .get("/:id", ({ params: { id } }) => `user ${id}`);

const app = new Elysia().use(userPlugin).listen(3000);

**Why good:** `name` prevents duplicate registration when a plugin is `.use()`-d multiple times, `prefix` scopes routes cleanly

See [examples/core.md](examples/core.md) for `.derive()`, `.decorate()`, and `.macro()` patterns.

---

Pattern 3: Scoping with Guard

Apply validation schemas and lifecycle hooks to groups of routes.

import { Elysia, t } from "elysia";

const app = new Elysia()
  .guard(
    {
      headers: t.Object({
        authorization: t.String(),
      }),
    },
    (app) =>
      app
        .get("/protected", ({ headers }) => headers.authorization)
        .post("/admin", ({ body }) => body, {
          body: t.Object({ action: t.String() }),
        }),
  )
  .get("/public", () => "no auth needed");

**Why good:** guard encapsulates validation for route groups without repeating schema definitions, public routes outside the guard are unaffected

---

Pattern 4: Error Handling with status()

Use `status()`