Claude Skill

api-framework-elysia

Bun-native HTTP framework — routing, TypeBox validation, Eden Treaty, plugins, lifecycle hooks

LLM Mart · 0 points · 3 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-framework-elysia_skills_api-framework-elysia-707467a.zip · 18 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-framework-elysia/skills/api-framework-elysia
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

(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:




<red_flags>

RED FLAGS

High Priority:

  • Separate app.get() / app.post() calls instead of chaining -- breaks Eden Treaty type inference entirely
  • Using deprecated error() function instead of status() -- deprecated since Elysia 1.3
  • Not exporting type App = typeof app -- Eden Treaty client has no type information
  • Using as('plugin') -- removed in 1.3+, use as('scoped') instead

Medium Priority:

  • Importing patterns from other HTTP frameworks -- Elysia has its own routing API and conventions
  • Using t.Object() without named constants for limits/lengths -- magic numbers in validation schemas
  • Not providing name on plugin instances -- causes duplicate registration in complex app trees
  • .derive() or lifecycle hooks without { as: 'scoped' } or { as: 'global' } when parent routes need them -- hooks are local-scoped by default

Gotchas & Edge Cases:

  • params are strings by default -- use t.Number() in the schema to coerce path params to numbers
  • .handle() in tests requires a fully qualified URL (http://localhost/path), NOT a path fragment (/path)
  • .guard() group standalone mode is default in 1.4+ -- guard schemas merge with route schemas instead of overwriting
  • TypeBox t.File() auto-detects multipart/form-data content type -- no need to set headers manually
  • t.Files() (plural) for multiple file uploads, t.File() for single
  • Eden Treaty dynamic path params use function syntax: api.user({ id: 1 }).get() not api.user[1].get()
  • When Eden Treaty response has status >= 300, data is always null and error has the value
  • Lifecycle hooks only apply to routes registered AFTER the hook -- order of .on*() and route definitions matters
  • onError receives a code string, not a status number -- switch on code for type narrowing
  • Cookies parse as JSON automatically if the value looks like JSON (1.3+ behavior)
  • await app.modules is required in tests when using lazy-loaded plugins (import('./plugin'))

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(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)

Failure to follow these rules will break end-to-end type safety and Eden Treaty client generation.

</critical_reminders>

Files (skills)
  • examples
    • core.md 9.2 KB
      Loading…
    • eden-treaty.md 5.5 KB
      Loading…
    • lifecycle-errors.md 9 KB
      Loading…
    • websocket-testing.md 7.2 KB
      Loading…
  • reference.md 8 KB
    Loading…
  • SKILL.md 10.3 KB
    ---
    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
    
    **(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.
    
    ```typescript
    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.
    
    ```typescript
    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.
    
    ```typescript
    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()` for typed error responses. Register custom error classes with `.error()`.
    
    ```typescript
    import { Elysia } from "elysia";
    
    const HTTP_UNAUTHORIZED = 401;
    const HTTP_NOT_FOUND = 404;
    
    class NotFoundError extends Error {
      status = HTTP_NOT_FOUND;
      constructor(public resource: string) {
        super(`${resource} not found`);
      }
    }
    
    const app = new Elysia()
      .error({ NotFoundError })
      .onError(({ code, error, status }) => {
        if (code === "NotFoundError") {
          return status(HTTP_NOT_FOUND, { error: error.message });
        }
        if (code === "VALIDATION") {
          return status(HTTP_UNAUTHORIZED, { error: "Validation failed" });
        }
      })
      .get("/user/:id", ({ params: { id }, status }) => {
        const user = findUser(id);
        if (!user) throw new NotFoundError("User");
        return user;
      });
    ```
    
    **Why good:** `status()` provides type narrowing for error responses, custom error classes with `.error()` enable `code`-based type narrowing in `onError`, named constants avoid magic status numbers
    
    See [examples/lifecycle-errors.md](examples/lifecycle-errors.md) for all lifecycle hooks and error patterns.
    
    ---
    
    ### Pattern 5: Eden Treaty Client
    
    Export the app type and use `treaty()` for a fully type-safe client with no code generation.
    
    ```typescript
    // server.ts
    import { Elysia, t } from "elysia";
    
    const app = new Elysia()
      .get("/user/:id", ({ params: { id } }) => ({ id, name: "Alice" }), {
        params: t.Object({ id: t.Number() }),
      })
      .post("/user", ({ body }) => body, {
        body: t.Object({ name: t.String() }),
      });
    
    export type App = typeof app;
    ```
    
    ```typescript
    // client.ts
    import { treaty } from "@elysiajs/eden";
    import type { App } from "./server";
    
    const api = treaty<App>("localhost:3000");
    
    const { data, error } = await api.user({ id: 1 }).get();
    // data is typed as { id: number; name: string } | null
    // error is typed based on error responses
    ```
    
    **Why good:** zero code generation, full autocomplete on paths and methods, error/data destructuring with type narrowing
    
    See [examples/eden-treaty.md](examples/eden-treaty.md) for response handling, file uploads, and WebSocket via Treaty.
    
    </patterns>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **High Priority:**
    
    - Separate `app.get()` / `app.post()` calls instead of chaining -- breaks Eden Treaty type inference entirely
    - Using deprecated `error()` function instead of `status()` -- deprecated since Elysia 1.3
    - Not exporting `type App = typeof app` -- Eden Treaty client has no type information
    - Using `as('plugin')` -- removed in 1.3+, use `as('scoped')` instead
    
    **Medium Priority:**
    
    - Importing patterns from other HTTP frameworks -- Elysia has its own routing API and conventions
    - Using `t.Object()` without named constants for limits/lengths -- magic numbers in validation schemas
    - Not providing `name` on plugin instances -- causes duplicate registration in complex app trees
    - `.derive()` or lifecycle hooks without `{ as: 'scoped' }` or `{ as: 'global' }` when parent routes need them -- hooks are local-scoped by default
    
    **Gotchas & Edge Cases:**
    
    - `params` are strings by default -- use `t.Number()` in the schema to coerce path params to numbers
    - `.handle()` in tests requires a fully qualified URL (`http://localhost/path`), NOT a path fragment (`/path`)
    - `.guard()` group standalone mode is default in 1.4+ -- guard schemas merge with route schemas instead of overwriting
    - TypeBox `t.File()` auto-detects `multipart/form-data` content type -- no need to set headers manually
    - `t.Files()` (plural) for multiple file uploads, `t.File()` for single
    - Eden Treaty dynamic path params use function syntax: `api.user({ id: 1 }).get()` not `api.user[1].get()`
    - When Eden Treaty response has status >= 300, `data` is always `null` and `error` has the value
    - Lifecycle hooks only apply to routes registered AFTER the hook -- order of `.on*()` and route definitions matters
    - `onError` receives a `code` string, not a status number -- switch on `code` for type narrowing
    - Cookies parse as JSON automatically if the value looks like JSON (1.3+ behavior)
    - `await app.modules` is required in tests when using lazy-loaded plugins (`import('./plugin')`)
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(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)**
    
    **Failure to follow these rules will break end-to-end type safety and Eden Treaty client generation.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.