daloyjs-best-practices

SKILL.md — DaloyJS best practices (Bun)

Operational guidance and best practices for AI coding agents working in this DaloyJS Bun project. This is the project's single source of truth for how to add routes, write tests, ship secure defaults, and run the quality gates. Read this in full before making non-trivial changes.

When to use this skill

Use this skill when you need to:

• Add, modify, or remove HTTP routes in this project.
• Regenerate the OpenAPI spec or the typed Hey API SDK in generated/.
• Wire up new middleware, validation, or error handling.
• Add or update tests, run typecheck, or build the project.
• Harden the API (auth, CORS, rate limits, secrets, dependency hygiene).
• User phrasing such as "add GET /books", "new endpoint", "regenerate the client", or "fix the 401".

Do not use this skill for frontend UI, infra-only work, or unrelated docs. Rare topics live under references/: read references/mcp.md only when adding an MCP endpoint, and read references/ci-workflows.md only when editing .github/ or a --with-ci workflow. Do not load those files up front.

Core principles

DaloyJS is a contract-first framework. Internalize these rules — every recommendation below follows from them:

1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — app.get(path, contract, handler) (and the matching app.post/put/patch/delete/head shorthands), or app.route({...}) when you need a reusable defineRoute() contract or a metadata-heavy route. Both forms produce identical runtime behavior, validation, security, and OpenAPI output. The OpenAPI spec, the typed client, and the runtime validation are all derived from the route definition.
2. Validation schemas protect every boundary. This template uses Zod, and Daloy accepts any Standard Schema-compatible library. Body, params, query, and headers go through the declared schema.
3. Preserve literal types. Return status: 200 as const and use z.literal(...) / as const on discriminator fields so the typed client can narrow responses.
4. buildApp() is pure. Construction never opens sockets. The HTTP listener lives in src/index.ts via @daloyjs/core/bun. This lets codegen and tests import buildApp() without side effects.
5. Secure by default. requestId(), secureHeaders(), and rateLimit() are registered before route definitions.
6. Contract gates are part of done. Keep operationId values stable, examples schema-valid, declared error responses accurate, and generated OpenAPI / client artifacts in sync with the live route table.