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

User asks forUseAlso read
Start an app, manage lifecycle, graceful shutdown@hile/core, @hile/cli, @hile/bootstrappackages/core-lifecycle.md
Create an HTTP endpoint or Koa middleware@hile/httppackages/http.md, recipes/http-api-model-typeorm.md
Run Next.js and API controllers on one port@hile/http-nextpackages/http-next.md, recipes/http-next-fullstack.md
Put business logic somewhere reusable@hile/modelpackages/model-context.md
Propagate request id, tenant id, logger bindings, or micro context@hile/contextpackages/model-context.md
Connect to SQL through TypeORM@hile/typeormpackages/core-lifecycle.md, packages/infrastructure.md
Connect to Redis@hile/ioredispackages/core-lifecycle.md, packages/infrastructure.md
Create structured logs@hile/loggerpackages/core-lifecycle.md, packages/infrastructure.md
Add read-through Redis cache@hile/cachepackages/infrastructure.md, recipes/redis-cache-singleflight.md
Run cron or delayed jobs@hile/schedulepackages/infrastructure.md
Build a custom file loader or understand route mapping@hile/loaderpackages/infrastructure.md
Add request/response messaging over WS/IPC/worker@hile/message-*packages/messaging-micro.md
Load file-based message handlers@hile/message-loaderpackages/messaging-micro.md, recipes/micro-rpc-message-loader.md
Build service discovery or RPC@hile/micropackages/messaging-micro.md, recipes/micro-rpc-message-loader.md
Push runtime config without restarts@hile/micro-dynamic-configspackages/messaging-micro.md, recipes/runtime-config.md
Stabilize config-driven runtime reloads@hile/reloaderpackages/reloader.md, recipes/stable-runtime-reload.md
Compose topics, config, and reloader state as refs@hile/reactivitypackages/reactivity.md, recipes/stable-runtime-reload.md
Protect a critical section with a lease@hile/redis-lockpackages/redis-reliability.md
Stop duplicate retry side effects@hile/redis-idempotencypackages/redis-reliability.md, recipes/queue-worker-idempotency.md
Enforce shared quotas or 429s@hile/redis-rate-limitpackages/redis-reliability.md
Persist and retry background jobs@hile/redis-stream-queuepackages/redis-reliability.md, recipes/queue-worker-idempotency.md
Scaffold a new projectcreate-hilepackages/create-hile.md, recipes/new-project-scaffold.md

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

​
Start With Examples

For implementation tasks, pick the package from the matrix and copy the closest recipe before writing custom abstractions.
  • HTTP API + model + TypeORM: docs/ai/recipes/http-api-model-typeorm.md
  • HttpNext fullstack app: docs/ai/recipes/http-next-fullstack.md
  • Redis cache with singleflight: docs/ai/recipes/redis-cache-singleflight.md
  • Queue worker with idempotency: docs/ai/recipes/queue-worker-idempotency.md
  • Micro RPC with message loader: docs/ai/recipes/micro-rpc-message-loader.md
  • Runtime dynamic config: docs/ai/recipes/runtime-config.md
  • New scaffolded project: docs/ai/recipes/new-project-scaffold.md