@hile/http

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

@hile/http

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

Choose This Package When

User asks for	Use	Also read
Create an HTTP endpoint or Koa middleware	@hile/http	packages/http.md, recipes/http-api-model-typeorm.md
Run Next.js and API controllers on one port	@hile/http-next	packages/http-next.md, recipes/http-next-fullstack.md

Use When

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

Do Not Use When

• 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.

Install

pnpm add @hile/http

Imports

import { Http, defineController, createControllerMetadata, defineResponsePlugin } from '@hile/http'
import { z } from 'zod'

Copy-Paste Example

import { defineController } from '@hile/http'

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

File route examples:

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

More Examples

import { z } from 'zod'
import { createControllerMetadata, defineController } from '@hile/http'

const bodySchema = z.object({
  username: z.string().min(1),
  age: z.number().int().nonnegative(),
})

export default defineController(
  createControllerMetadata({
    method: 'POST',
    schema: { body: bodySchema },
  }),
  async (ctx) => {
    const body = bodySchema.parse(ctx.request.body)
    return { created: true, user: body }
  },
)

The second parse is intentional when you need parsed/coerced data. Hile’s controller validation does not write safeParse().data back to ctx.request.body.

Runtime And Lifecycle Notes

• new Http({ port }) creates a Koa app and a find-my-way router.
• http.use(middleware) registers Koa middleware before listen().
• http.listen() returns a close function.
• http.load(directory, options) scans *.controller.{ts,js,tsx,jsx,mjs} by suffix.
• defineController() supports method-only, method-plus-middlewares, and metadata-plus-Zod forms.
• Response plugins transform handler return values and set ctx.body when the final result is not undefined.

Anti-Patterns

• 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.

Verification Checklist

• 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.

Related Recipes

HTTP API + Model + TypeORM

Complete Example

Controller:

// src/controllers/users/[id].controller.ts
import { defineController } from '@hile/http'
import { loadModel } from '@hile/model'
import { getUser } from '../../models/users/get-user.model'

export default defineController('GET', async (ctx) => {
  return loadModel(getUser, { userId: String(ctx.params.id) })
})

Model:

// src/models/users/get-user.model.ts
import { defineModel } from '@hile/model'
import typeormService from '@hile/typeorm'
import { User } from '../../entities/user.entity'

export const getUser = defineModel({
  services: [typeormService] as const,
  async main([ds], input: { userId: string }) {
    const user = await ds.getRepository(User).findOneBy({ id: input.userId })
    if (!user) return { found: false }
    return { found: true, user }
  },
})

Boot file:

// src/services/http.boot.ts
import { defineService } from '@hile/core'
import { Http } from '@hile/http'

export default defineService('http', async (shutdown) => {
  const http = new Http({ port: Number(process.env.HTTP_PORT ?? 3000) })
  await http.load(new URL('../controllers', import.meta.url).pathname)
  const close = await http.listen()
  shutdown(close)
  return http
})

Package config:

{
  "type": "module",
  "scripts": {
    "dev": "hile start --dev --env-file .env",
    "start": "hile start --env-file .env.prod"
  },
  "hile": {
    "auto_load_packages": ["@hile/typeorm"]
  }
}

Package-Local AI Guide

This package also ships AI.md in npm so agents can read accurate examples after installation.