elysia

Elysia

Use this skill when the work touches Elysia or ElysiaJS.

Workflow

1. Inspect the application before proposing changes:
   • Installed versions of elysia and relevant @elysia/* packages. Stable latest is 1.4.x (security fixes only); 2.0.0-beta.x is published under the next dist-tag and changes core APIs. Never mix 1.4 and 2.0 syntax in one app.
   • On 1.4.x, require >= 1.4.30 (critical RCE advisory for schema defaults and property names in <= 1.4.29).
   • Runtime and adapter: Bun, @elysia/node, Deno, Cloudflare Worker, Vercel, Netlify, or another Web Standard host.
   • Root instance, export/listen shape, route plugins, prefixes, guards, macros, schemas, error hooks, and tests.
   • Registration order and plugin scope for every cross-cutting hook.
2. Refresh current official docs when the task depends on latest APIs, adapters, package compatibility, experimental support, or version-specific behavior. Start from source-map.md.
3. Route the work to the focused references:
   • Setup, routing, handlers, streaming, and project layout: setup-routing.md.
   • Schemas, lifecycle order, status responses, and errors: validation-lifecycle-errors.md.
   • Plugins, scope, guards, macros, dependencies, and context: plugins-context.md.
   • Tests, Eden, OpenAPI, WebSocket, and SSE: testing-clients-realtime.md.
   • Runtimes, deployment, security, observability, and production checks: production-runtime-security.md.
   • Elysia 2 beta adoption, codemod, and 1.4-to-2.0 API changes: elysia-2-migration.md.
4. Preserve the repository's existing architecture and commands unless the user explicitly asks for a migration.
5. Verify behavior at the narrowest useful boundary, then verify the assembled application.

Core Judgment

• Treat schemas as executable HTTP contracts. Define request and per-status response schemas where the boundary matters; do not duplicate them with hand-written interfaces.
• Keep route handlers thin. Prefer feature-scoped Elysia instances for HTTP concerns and ordinary functions/modules for business logic that does not need request context.
• Export a const Elysia instance from each route/plugin file. Do not wrap routes in export function featureRoutes(db) / (runtime) / similar factories.
• Import app singletons (database client, Effect ManagedRuntime, env, mailer) in the module that uses them. Services import the DB; routes import runtime only to runPromise. Do not pass those values as function arguments, and do not .decorate("db", db) (or runtime) just to thread them through handlers.
• Plugin factories that accept options are only for reusable/shared plugins (config such as prefix, version, CORS origins). They are not how the app wires its database or runtime into features.
• Let Elysia infer handler context. Do not pass a broad manually typed Context through controllers or services when destructured values or schema-derived types are sufficient.
• Respect chain order. Interceptor hooks apply to routes and plugins registered after them, except onRequest, which is global to incoming requests.
• Respect plugin encapsulation. A plugin's lifecycle hooks and schemas do not automatically protect parent routes. Choose local, scoped, or global deliberately and test the boundary.
• On 1.4, prefer resolve over derive when a value depends on validated request data. derive runs before validation; resolve runs after validation. On 2.0, resolve is removed and derive runs at before-handle (the old resolve timing).
• Never build schemas, property names, or default values from untrusted input (form builders, database-driven schemas). Elysia compiles them into generated code.
• Return status(code, value) for expected HTTP outcomes when type-safe response narrowing matters. On 1.4, throw only when the outcome should pass through onError; on 2.0, returned and thrown errors both reach error hooks.
• Use named plugins, plus seed when configuration changes identity, when lifecycle deduplication matters.
• Treat OpenAPI security declarations as documentation only. Enforce authentication and authorization in guards, macros, hooks, or handlers.
• Do not assume Bun-only APIs on other adapters. server and server.requestIP are Bun-specific; adapter and platform limitations must shape the implementation.
• Do not quote benchmark numbers as general application performance guarantees. Profile the actual app and runtime.
• Test HTTP endpoints with Eden Treaty (treaty(app) from @elysia/eden). Ban app.handle(new Request(...)), plugin.handle(...), and helpers such as const handle = (path) => app.handle(new Request(\http://localhost${path}\`))`.

Verification

Prefer repository-owned commands. For meaningful Elysia changes, cover the relevant subset:

• Typecheck and production build with the actual runtime/adapter.
• Eden Treaty tests (treaty(app)) for success, validation failures, auth failures, error mapping, headers, and status-specific response bodies. Assert { data, error, status }.
• Scope/order regression tests when changing hooks, guards, macros, or plugin composition (still via Treaty).
• await app.modules before Treaty calls against deferred or lazy-loaded plugins.
• Generated OpenAPI inspection when schemas, response status maps, tags, security metadata, or type generation changes.
• Real HTTP smoke test for listen/export, proxy headers, cookies, CORS preflight, streaming, and runtime-specific behavior.
• WebSocket connection, invalid-message, close, timeout, and backpressure checks when realtime behavior changes.
• Deployment-target smoke test when changing adapters, bundling, binary compilation, serverless exports, environment variables, or platform bindings.

Report which checks ran, which did not, and any version-sensitive assumptions that remain.