Skip to main content

​
Deployment

Build TypeScript before production hile start. In development, hile start --dev imports src/**/*.boot.ts; in production it imports dist/**/*.boot.js.

​
Runtime And Lifecycle Notes

  • defineService(key, fn) registers a service factory and does not execute it.
  • loadService(service) executes the factory on first call and returns the cached value afterwards.
  • The shutdown callback registers teardown functions; they run in LIFO order.
  • The container tracks dependencies when service factories call loadService().
  • container.shutdown() triggers registered teardowns.
  • @hile/bootstrap loads env files first, sets NODE_ENV, imports auto-load packages, scans boot files, and installs exit hooks.
  • @hile/logger.createLogger() returns { logger, teardown }.
  • @hile/ioredis.createRedis() waits for connect.
  • @hile/typeorm.createDataSource() initializes a TypeORM DataSource.

​
Runtime And Lifecycle Notes

  • HttpNext keeps its internal Http instance private and exposes only use(), load(), and start().
  • Hile middleware and controllers run first; unmatched requests are passed to Next.js with the original Node request and response.
  • Development mode is determined by process.env.NODE_ENV === 'development'.
  • Controllers use {cwd}/src/controllers in development and {cwd}/dist/controllers in production with prefix /-.
  • load(directory) explicitly loads an additional controller directory with the same fixed conventions.
  • Call use() and load() before start(); configuration is frozen once startup begins.
  • Next.js exclusively owns public/, distDir, /_next/static, RSC, Server Functions, and next.config.
  • start(onReady) calls readiness only after Next is prepared and the shared HTTP server is listening.
  • The returned async stop function first asks the shared HTTP server to stop accepting new connections, then waits for HTTP drain and Next runtime cleanup concurrently. It tracks and terminates upgraded connections, including development HMR WebSockets, because Node’s HTTP drain does not own their protocol lifecycle. Development shutdown also closes disposable HTTP/compiler connections, matching Next’s own development-server policy; production HTTP requests retain graceful drain behavior.
  • Stop and startup rollback attempt both HTTP and Next cleanup even when either side fails. One failure is rethrown directly; multiple failures are reported together.

​
Production Checklist

  • Register every server/client close function with shutdown.
  • Load controllers before listen() in new code.
  • Size Redis lock TTLs for the actual job duration.
  • Monitor queue DLQs and idempotency release failures.
  • Keep DB constraints or provider idempotency keys for irreversible side effects.