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().
  • Except for cwd, constructor options are the HttpProps passed unchanged to the shared Http instance, including complete Koa options, bounded reverse-proxy trust, and router options.
  • Hile middleware and controllers run first; unmatched requests are passed to Next.js with the original Node request and response.
  • @hile/http-next/request-signal is the Next-free App Router entrypoint for reading the current request’s cancellation signal.
  • Concurrent requests, multiple HttpNext instances, and compatible package copies in one JavaScript realm share one storage identity while retaining isolated asynchronous contexts. Separate PM2 processes, Workers, or VM realms intentionally keep independent request signals.
  • 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 /-.
  • Required catch-all controllers use the same [...name] final-segment convention as @hile/http; unmatched requests alone continue to Next.js.
  • 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.
  • Normal stop attempts HTTP, Next, and startup-loaded controller cleanup even when one side fails. One cleanup failure is rethrown directly and multiple cleanup failures are reported together. Startup rollback also attempts every acquired cleanup, then preserves the original startup error.

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