Skip to main content

Server Runtime Phase

The runtime phase covers the journey of a request from the Hapi.js engine through the Archibald framework layers to the final React-rendered response.

The Hapi layer​

Hapi.js is the HTTP engine embedded in @archibald/server — it is not a separate package on this line, and no direct import is ever required. Your controllers, plugins and modules are written against @archibald/server and stay unaware of Hapi. The Hapi layer owns:

  • Server lifecycle — server creation, start/stop, route registration and the request/response lifecycle handed to the framework's CoreServer.
  • CSRF protection — a crumb-based plugin built on @hapi/crumb.
  • Swagger UI — serves API docs through swagger-ui-dist (see the Swagger configuration guide).
  • Static files & proxying — via @hapi/inert and @hapi/h2o2.
  • Error translation — maps framework errors to HTTP responses via @hapi/boom.

Request & SSR Pipeline​

  1. Hapi Router: Receives the request and invokes the handler.
  2. CoreServer.decorateController: Wraps the execution in a ServerContext stored in AsyncLocalStorage (via @archibald/storage).
  3. RenderService: Instantiates the Renderer and passes the React tree.
  4. Renderer: Uses renderToPipeableStream for non-blocking HTML delivery.

The Role of AsyncLocalStorage​

By using AsyncLocalStorage, Archibald allows any service or helper to call getServerContext() to get the current request, user, or config without needing to pass these objects through every function signature. This is critical for maintaining an isomorphic codebase.