Skip to content
Skills Library
Programming · Building & coding

building-api-modules

/building-api-modules

Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.

Licence
MIT
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.

Original author description

Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.

How it works

  1. Module layout
  2. Steps for a new module
  3. Rules that are easy to miss
Original SKILL.md headings · 52 lines, 294 words
SKILL.md preview
---
name: building-api-modules
description: Adds or changes an Elysia 2 + Effect v4 API module following the controller/service/error/mapper split, the ok/fail response envelope, and the Effect-at-the-boundary rules. Use when creating or editing a domain module under apps/api.
---

# Building API modules

Elysia 2 (Kiana) + Effect v4 backend. Read `apps/api/AGENTS.md` first — it is the
authoritative rule set. This skill is the step-by-step path.

## Module layout

One directory per domain under `apps/api/src/modules/<name>/`:

```text
modules/<name>/
├── index.ts     Elysia controller — HTTP only, thin
├── service.ts   business logic (Effect service when it has deps/errors)
├── error.ts     domain errors (Schema.TaggedError)
├── mapper.ts    database row → shared wire type
```

Reference implementations: `modules/session/progression.ts` (pure logic, plain
function) and `modules/interview` (real dependency + typed error, full Effect
service).

## Steps for a new module

1. Add the request/response schemas to `packages/shared/src/schemas/` as Effect
   `Schema.Struct` (wire timestamps are ISO strings). Re-export from the index.
2. Write `service.ts`:
   - **Pure logic** → a plain function (`modules/session/progression.ts`). Do NOT
     wrap it in `Context.Service`/`Layer`/`ManagedRuntime`.
   - **Real effect** (async, typed error, resource, dependency) → `Context.Service`
     - `Layer` + `Schema.TaggedError` (`modules/interview/service.ts` + `error.ts`).
3. Write `error.ts` for domain failures with `Schema.TaggedError`.
4. Write `mapper.ts` mapping the Drizzle `$inferSelect` row to the shared wire type.
5. Write `index.ts`: a thin Elysia controller. Return `ok(...)`, declare `response`
   with `Schema.toStandardSchemaV1(ApiSuccessSchema(...))` and OpenAPI `detail`.
   Run effects at the boundary: `runtime.runPromise` (async) or `runtime.runSync`
   (sync) from `src/runtime.ts`, via `Service.use((s) => s.method(...))`.
6. If the module has a service layer, add it to the single runtime in
   `src/runtime.ts` (`ManagedRuntime.make(Layer.mergeAll(...))`).
7. If it has new errors, map them in `plugins/logger.ts` `resolveErrorDefinition`
   (by `_tag`/`code`) to the envelope.

## Rules that are easy to miss

- Every response is `{ ok: true, data }` or `{ ok: false, error, requestId }`.
  Never return a bare payload.
- `yield*` inside Effect, `await` only at the controller boundary.
- `Layer.succeed` for stateless services, `Layer.effect` for stateful/dependent,
  `Effect.acquireRelease` for resources.
- Never leak internal error details; `resolveErrorDefinition` maps everything to a
  stable code/message.

Versions

The database has no other skills named building-api-modules.

Database snapshot: 13.11.2026 · package version 82bfcb5cd522 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86add-resource
    Add a REST resource to this NestJS API end to end, as a feature module with its controller, service, DTOs, unit spec and contract tests. Use when asked for a new resource, endpoint, route or feature module.
  • 91effect-development
    Effect development guidance. Use when implementing or reviewing code that composes Effect APIs or patterns, or that adds or changes API signatures.
  • 100elysiajs
    Build, debug, or migrate Elysia v2 TypeScript backends with validation, plugins, typed clients, and deployment. Use for Elysia projects or explicit Elysia requests.
  • 95effect-service-design
    Design Effect services. Use when designing a new Effect service module or auditing an existing codebase for service, Layer, and composition improvements.
  • 100java-crud-module
    Use when scaffolding a new CRUD business module in a Spring Boot + MyBatis-Plus layered project. Covers the full 9-file flow: migration, entity, mapper, DTOs, converter, service, facade, and controller.
  • 100effect-v3-to-v4
    Use this skill when migrating a codebase from Effect v3 to Effect v4, upgrading `effect` or any `@effect/*` package across the v3/v4 boundary.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.