# @hile/http

<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->

Build Koa HTTP APIs with file-system controllers, middleware, response plugins, and Zod validation.

This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.

## When To Use

Use `@hile/http` for Koa-based APIs, middleware, manual routes, file-system controllers, Zod validation, and response plugins.

## Install

```bash
pnpm add @hile/http
```

## Copy-Paste Example

```ts
import { defineController } from '@hile/http'

export default defineController('GET', async () => {
  return { ok: true }
})
```

File route examples:

```text
src/controllers/index.controller.ts -> /
src/controllers/users/index.controller.ts -> /users
src/controllers/users/[id].controller.ts -> /users/:id
```

## Boundaries

- Do not use it for Next.js pages; use `@hile/http-next` when Next.js and API routes share a port.
- Do not assume Zod validation mutates/coerces Koa context data. It validates only.

- Setting `ctx.body` and returning a value from the same controller.
- Loading controllers after starting only because an old example does it; prefer load before listen in new code.
- Using old validation examples that assume Zod coercion rewrote `ctx.query`.

## Verify

- Controller files default-export `defineController(...)` or an array of controllers.
- Controllers return response values.
- Boot service awaits `http.load()` before `http.listen()`.
- Zod schemas are used for validation, and parsed data is explicitly parsed when needed.

## More Context

- `AI.md` in this package: full package-local AI guide.
- Root `llms-full.txt`: full monorepo AI context.
- Root `references/`: source files copied from `docs/ai`.