Introduction

Example-first overview of Hile packages and AI-facing usage rules.

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 for	Use	Also read
Start an app, manage lifecycle, graceful shutdown	@hile/core, @hile/cli, @hile/bootstrap	packages/core-lifecycle.md
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
Put business logic somewhere reusable	@hile/model	packages/model-context.md
Propagate request id, tenant id, logger bindings, or micro context	@hile/context	packages/model-context.md
Connect to SQL through TypeORM	@hile/typeorm	packages/core-lifecycle.md, packages/infrastructure.md
Connect to Redis	@hile/ioredis	packages/core-lifecycle.md, packages/infrastructure.md
Create structured logs	@hile/logger	packages/core-lifecycle.md, packages/infrastructure.md
Add read-through Redis cache	@hile/cache	packages/infrastructure.md, recipes/redis-cache-singleflight.md
Run cron or delayed jobs	@hile/schedule	packages/infrastructure.md
Build a custom file loader or understand route mapping	@hile/loader	packages/infrastructure.md
Add request/response messaging over WS/IPC/worker	@hile/message-*	packages/messaging-micro.md
Load file-based message handlers	@hile/message-loader	packages/messaging-micro.md, recipes/micro-rpc-message-loader.md
Build service discovery or RPC	@hile/micro	packages/messaging-micro.md, recipes/micro-rpc-message-loader.md
Push runtime config without restarts	@hile/micro-dynamic-configs	packages/messaging-micro.md, recipes/runtime-config.md
Stabilize config-driven runtime reloads	@hile/reloader	packages/reloader.md, recipes/stable-runtime-reload.md
Compose topics, config, and reloader state as refs	@hile/reactivity	packages/reactivity.md, recipes/stable-runtime-reload.md
Protect a critical section with a lease	@hile/redis-lock	packages/redis-reliability.md
Stop duplicate retry side effects	@hile/redis-idempotency	packages/redis-reliability.md, recipes/queue-worker-idempotency.md
Enforce shared quotas or 429s	@hile/redis-rate-limit	packages/redis-reliability.md
Persist and retry background jobs	@hile/redis-stream-queue	packages/redis-reliability.md, recipes/queue-worker-idempotency.md
Scaffold a new project	create-hile	packages/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