elysia_skill

Overview

This skill documents Elysia.js server patterns for consistent error handling, status responses, and plugin composition. It focuses on using the status() helper, Eden Treaty response typing, and clear conventions for route handlers and plugins. Follow these patterns to get typesafe, self-documenting APIs and predictable control flow.

How this skill works

Destructure status from the route handler context and call status(codeOrString, message) for all non-200 responses to produce ElysiaCustomStatusResponse objects. Define response schemas per status code in route options so Eden Treaty infers error types end-to-end. Use return status(...) for normal control flow and throw status(...) only to short-circuit deep logic or catch blocks.

When to use it

• When writing Elysia route handlers that return errors or non-200 responses
• When you want end-to-end type safety with Eden Treaty for error responses
• When converting legacy handlers that use set.status and object error bodies
• When composing reusable Elysia plugins that consumers will mount with prefixes
• When applying shared auth using guards and beforeHandle

Best practices

• Always destructure status from handler context and prefer return status(...) for early-return guards
• Prefer string literal statuses (e.g. 'Bad Request') for readability and IntelliSense; use numeric codes only for nonstandard cases like 499
• Define response schemas per status code so client-side error.status and error.value are properly typed by Eden Treaty
• Prefer plain string error bodies for simplicity; use TypeBox schemas only when structured error data is required
• Write plugins as prefix-agnostic Elysia instances and let the consumer control mounting with prefixes

Example use cases

• A POST /chat handler that validates provider and returns status('Bad Request', message) on invalid input
• A streaming handler that throws status(499, 'Client closed request') inside a catch when the client aborts
• A shared auth guard using .guard({ beforeHandle }) that returns status('Unauthorized', message) for invalid tokens
• A reusable plugin built with new Elysia() that exposes endpoints; consumer mounts it with a prefix
• Migrating legacy handlers: replace set.status + object returns with return status(stringLiteral, message) and add response schemas