Elysia

---
name: elysia
description: Expert guide for building APIs with the Elysia framework, including routing, validation, plugins, error handling, and type-safe handlers. Use when building APIs with Elysia framework, defining routes, plugins, or type-safe handlers.
allowed-tools: Read, Grep, Glob
---

# Elysia Developer Guide

This skill provides guidelines, patterns, and best practices for working with the Elysia framework in this project.

## Quick Start

For detailed development guidelines, imports, and patterns, please refer to `references/patterns.md` in this skill directory.

## Core Philosophy

- **Pattern-agnostic but feature-based** structure recommended
- **"1 Elysia instance = 1 controller"** principle
- **Strong typing** with TypeBox for runtime validation
- **Centralized error handling** and consistent responses
- **Production-ready** deployment strategies

## Structure, Routing & Controllers

### Essential Organization Patterns

- **App as controller**: Treat each `new Elysia({ prefix })` instance as the controller for that feature. Do **not** pass entire class methods directly as handlers. Instead, inline a small handler that calls service functions.
- **Feature folders**: Use a feature-based structure:
  - `src/modules/<feature>/index.ts` - Elysia controller (routes, guards, cookies)
  - `src/modules/<feature>/service.ts` - business logic (no HTTP context)
  - `src/modules/<feature>/model.ts` - schemas & types via `t` (TypeBox)
  - Keep shared utilities in `src/utils/*`.
- **Method chaining**: Prefer fluent chaining on the Elysia instance for routes, guards, plugins.
- **Plugins**: Encapsulate cross-cutting concerns in plugins via `.use()` (e.g., OpenAPI, JWT, CORS).
- **Context hygiene**: If a service needs request data, keep it in the controller and pass only the relevant fields into the service function.

### Feature Scaffolding Pattern

When scaffolding a feature, generate:

1. `model.ts` with `t.Object(...)` schemas and exported `type` aliases via `typeof schema.static`.
2. `service.ts` with pure functions (or an `abstract class` of statics when no instance state is needed).
3. `index.ts` that mounts the Elysia routes, applies `guard()` with shared validation, and returns typed responses.

## Validation, Schemas & Types

### Runtime Validation + Static Types

- Use `import { t } from 'elysia'` to define **Body**, **Query**, **Params**, **Headers**, **Cookie**, and **Response** schemas.
- Derive TS types from `typeof schema.static` and export them (e.g., `export type SignInBody = typeof signInBody.static`).
- Apply shared validation with `.guard({ ... })`. If combining guards, consider `schema: 'standalone'` to keep them independent.
- Validate **files** by content: use `fileType` (magic number) when using standard schema systems.
- Ensure **response** schemas are present for 2xx and error variants for strong end-to-end typing.

### Handler Schema Guidelines

When generating handlers:

- Include the 3rd argument schema object with `body/query/params/headers/cookie/response`.
- Don't parse body for GET/HEAD (Elysia follows HTTP spec).
- Provide examples with `t.Object`, `t.Array`, `t.Union`, `t.Literal`, file schemas, and show `guard()` for shared query/headers.

## Error Handling & Response Shape

### Centralized Error Management

- Use `.onError(({ code, error, path, request }) => { ... })` on the app to map framework and custom errors to a **uniform JSON** shape (e.g., `{ ok: false, error: { code, message, details } }`).
- Prefer `throw status(code, messageOrPayload)` for error control flow that `onError` can catch. Note: `return status(...)` won't be caught by `onError`.
- Validation errors: normalize them to a predictable JSON (array of issues) while hiding sensitive internals in production.
- Include correlation ids (e.g., `x-request-id`) and log within `onError`. Avoid leaking stack traces in production.
- For success responses, optionally wrap in `{ ok: true, data }` for uniformity.

### Error Plugin Structure

When generating code, create:

- `src/plugins/error.ts` that installs `.onError(...)`.
- Optionally `src/plugins/logging.ts` to log in `onResponse` & `onError`.

## OpenAPI, Auth & Cross-cutting

### OpenAPI

- Add `@elysiajs/openapi` plugin and expose docs route (Scalar UI).
- Keep **response** schemas accurate - OpenAPI derives from them.
- If building SDKs, ensure routes are fully typed and examples provided.

### Auth

- Use `@elysiajs/jwt` for JWT signing/verification, or integrate with your auth of choice.
- Keep auth in a plugin that decorates context with `user` after verification.
- Protect routes via `.guard({ headers: t.Object({ authorization: t.String() }) })` and verify bearer tokens before handlers.

### Cross-cutting Plugins

- Install `@elysiajs/cors` where needed.
- Consider `@elysiajs/server-timing` and `@elysiajs/opentelemetry` for observability.

When scaffolding, generate `src/plugins/openapi.ts`, `src/plugins/auth.ts`, and wire them in `src/app.ts`.

## Deploy, Performance & Docker

### Production Deployment

- **Cluster mode** for multi-core: use a small launcher (`index.ts`) that forks workers and imports `server.ts` per worker.
- Prefer building with bundlers like Vite or esbuild for production deployments.
- If compiling interferes with tracing (OpenTelemetry), avoid `--minify` or mark instrumented modules as `--external`.
- Accept `process.env.PORT` (with fallback) and bind `0.0.0.0` for PaaS.

### Docker

- Build stage: use Node.js base image with pnpm.
- Runtime: **distroless** base, copy binary, `CMD ["./server"]`.

### Deployment Scaffolding

When generating a deploy scaffold, include:

- `src/index.ts` (cluster launcher), `src/server.ts` (app), `Dockerfile` (multi-stage), and build scripts.

## Testing

### Unit Tests

- Use `vitest`.
- Import the app and use `app.handle(new Request(url, options))` to assert status/body/headers.
- For service tests, call pure functions directly.

### Test Examples to Include

- Simple GET test returning text.
- POST with `body` validation (both valid and invalid paths).
- Authenticated route example using a mocked `Authorization` header.
- Prefer small, focused tests per route and per service.

## Quick Utilities

### Common Patterns

- App context: use `.state()` and `.decorate()` to add version info, helpers, etc., then read from `{ store, getDate }`.
- WebSocket endpoints via `.ws()` for simple real-time APIs.
- Custom body parser with `.onParse()` for special content types.

## Validation Checklist

Before finishing a task involving Elysia:

- [ ] Feature structure follows `model.ts`, `service.ts`, `index.ts` pattern.
- [ ] All handlers have proper schema definitions (body/query/params/response).
- [ ] Error handling uses centralized `.onError()` plugin.
- [ ] Response schemas are defined for OpenAPI generation.
- [ ] Tests use `app.handle(new Request(...))` pattern.
- [ ] Run type checks (`pnpm run typecheck`) and tests (`pnpm run test`).

For detailed patterns and code examples, see `references/patterns.md`.