Skip to main content

​
Hile

Hile is a lightweight Node.js service toolkit for HTTP APIs, Next.js apps, reusable models, message-based microservices, jobs, and Redis-backed reliability primitives. The docs in this repository are generated from the same AI context that powers skills/hile/, llms.txt, llms-full.txt, and every package AI.md.

​
Core Mental Model

  • @hile/core manages resources as async services. A boot file starts things; shutdown() callbacks release them.
  • @hile/http exposes Koa routes and file-system controllers.
  • @hile/model is the reusable business-logic layer. Controllers and Next.js pages should call models instead of duplicating domain logic.
  • @hile/micro uses message loaders and WebSocket clients for service discovery and RPC.
  • Redis primitives (redis-lock, redis-idempotency, redis-rate-limit, redis-stream-queue, cache) are distributed coordination helpers, not exactly-once systems.

​
Package Selection Matrix

​
Common Selection Rules

  • If the task is a user-facing API, start with @hile/http or @hile/http-next.
  • If the task is reusable business behavior, put it in @hile/model even if the caller is HTTP, Next.js, queue, or micro.
  • If the task may retry or redeliver and has side effects, add @hile/redis-idempotency.
  • If the task is background work, use @hile/redis-stream-queue; do not use micro RPC as a queue.
  • If the task is “only one replica should run this”, use @hile/redis-lock or @hile/schedule distributed mode, and keep a final business consistency wall.
  • If the task is “prevent too many attempts”, use @hile/redis-rate-limit; do not confuse it with authentication or idempotency.
  • If config changes can arrive in bursts, use @hile/reloader around the runtime; do not reload directly inside every subscribe callback.
  • If service code needs refs or async watch strategies for topics/config/reloader state, use @hile/reactivity.
  • If tools, resources, and prompts belong to different microservices, use @hile/mcp; do not centralize their handlers in the gateway.

​
Start With Examples

For implementation tasks, pick the package from the matrix and copy the closest recipe before writing custom abstractions.