remotion_service/.agents/skills/elysia-best-practices/SKILL.md

name, description

name	description
elysia-best-practices	Use when writing, reviewing, or refactoring Elysia server code in this repository, including route handlers, schemas, response statuses, lifecycle hooks, plugins, OpenAPI docs, health checks, render API endpoints, and queue-facing API behavior.

Elysia Best Practices

Overview

Apply current Elysia guidance to this Bun Remotion rendering service while preserving its API contract: /api/render can enqueue async jobs, render synchronously, report BullMQ status, cancel jobs, and expose health checks.

Workflow

1. Fetch current Elysia docs first with Context7. This repo currently uses elysia 1.4.27, @elysiajs/openapi 1.4.14, and @elysiajs/swagger 1.3.1; compare docs against those packages before adopting examples that use newer @elysia/openapi imports.
2. Identify the layer being changed:
   • HTTP entrypoint: server/index.ts
   • Shared request schemas: server/types/DocumentSchema.ts, server/types/CaptionStyleSchema.ts
   • Queue behavior: server/services/render_queue.ts
   • Rendering and cleanup: server/services/render_video.ts
   • S3/webhooks/config: server/services/s3.ts, server/services/webhook.ts, server/config.ts
3. Keep Elysia routes thin. Validate and shape HTTP inputs at the route, then delegate rendering, queue, upload, and webhook work to services.
4. Verify with bun run lint and a focused smoke test through bun run server, /api/health, and the affected /api/render path.

Project Map

• Runtime: Bun with strict TypeScript and path aliases from tsconfig.json.
• Server root: new Elysia({ prefix: "/api" }) in server/index.ts.
• Current endpoints:
  • POST /api/render: async queue when callbackUrl is present; synchronous render/upload fallback otherwise.
  • GET /api/render/:renderId: BullMQ job state and progress.
  • DELETE /api/render/:renderId: cancellation.
  • GET /api/health: liveness response.
• Existing schemas use Elysia t and Static; reuse this style instead of introducing Zod, Valibot, or ad hoc runtime checks.

Route Contracts

• Define schemas for body, params, query, headers, and response. Elysia infers handler types from schemas, so avoid duplicate TypeScript interfaces unless they are exported from Static<typeof Schema>.
• For route responses with multiple statuses, define response by status code and return status(code, body) from the handler. Prefer this for new code over mutating set.status; current docs call set.status legacy and it cannot validate response types as precisely.
• Preserve existing API payload field names unless intentionally migrating a client contract: renderId, status, progress_pct, output_path, callback_delivered, and error.
• Use literal unions for finite render states and style values. Keep captions and transcription schemas reusable in server/types/, not embedded inside handlers.
• Validate URL-like inputs that leave the service boundary. For new fields such as callback or source URLs, prefer a schema-level constraint or a small service validator before queueing work.

Status And Errors

• Use the handler context status() function for expected outcomes: return status(202, { renderId, status: "queued" }) and return status(404, result).
• Use onError for cross-cutting logging and sanitized error responses, and register it before routes it must affect. Do not leak S3 credentials, signed URLs, local output paths, full Remotion CLI logs, or Redis connection details.
• Validation failures normally return 422. In production, Elysia omits detailed validation internals by default; keep that behavior unless debugging explicitly requires a temporary override.
• When adding typed domain errors, register classes with .error() and narrow in .onError(). For one route only, use a local route error hook.

Lifecycle And Plugins

• Hook order matters. Interceptor hooks apply only to routes registered after them; place auth, tracing, error mapping, CORS, or request logging before the routes they should cover.
• Elysia plugin lifecycles and schemas are encapsulated by default. Use local, scoped, or global intentionally when extracting route groups or shared guards, especially if a guard should affect parent /api routes.
• Prefer resolve for per-request values that depend on validated data, such as a parsed render ID, normalized callback URL, or tenant/folder value. Use derive for request-derived context before validation only when validation is not needed first.
• Use decorate for stable shared services or helpers, not request-specific mutable data. Avoid putting queue job state in Elysia store; BullMQ and Redis are the source of truth.
• If route count grows, extract plugins by concern, for example renderRoutes, healthRoutes, and openApiPlugin, then mount them under the existing prefixed app.

OpenAPI

• If exposing docs, prefer one OpenAPI integration and make it match installed packages. This repo already has @elysiajs/openapi and @elysiajs/swagger; do not add @elysia/openapi without an intentional dependency migration.
• Add detail metadata for public endpoints: tags, summary, description, and response examples where helpful. Keep docs accurate by defining runtime schemas for request and response shapes.
• Treat render endpoints as operational API, not demo routes. Document async queue behavior, callback delivery, cancellation semantics, and sync fallback separately.

Service Boundaries

• Do not start extra BullMQ workers from route modules. The current server starts one worker at process boot; keep worker lifecycle explicit and graceful.
• Keep cleanup in finally when route code creates local render outputs. Do not leave generated videos or props files behind after uploads or failures.
• Avoid blocking request handlers with long synchronous work unless preserving the existing no-callbackUrl sync fallback. Prefer queueing for new expensive render operations.
• Keep env requirements in server/config.ts and .env.example together. Never hardcode credentials, bucket names, Redis URLs, or public host assumptions in Elysia handlers.

Validation

• Always run bun run lint after TypeScript/Elysia changes.
• For schema or status changes, smoke invalid requests and expected non-200 responses, not only the happy path.
• For queue-facing changes, smoke POST /api/render with callbackUrl, GET /api/render/:renderId, and DELETE /api/render/:renderId.
• For docs changes, verify the generated OpenAPI page/spec if the plugin is mounted.

Source Anchors

• Validation and response schemas: https://elysiajs.com/tutorial/getting-started/validation/
• Handler context and status(): https://elysiajs.com/essential/handler
• Lifecycle and hook ordering: https://elysiajs.com/essential/life-cycle
• Error handling: https://elysiajs.com/patterns/error-handling
• Encapsulation, scopes, and guards: https://elysiajs.com/tutorial/getting-started/encapsulation/
• OpenAPI patterns: https://elysiajs.com/patterns/openapi