hapi

name	hapi
description	Creates, configures, and debugs `@hapi/hapi` servers — implements routes, plugins, auth schemes, validation, caching, and request lifecycle hooks. Use when building HTTP APIs, setting up stale-while-revalidate caching, registering server methods, configuring views, managing startup sequences, or troubleshooting response marshalling.

Hapi

Quick Start

const server = Hapi.server({ port: 3000 });
server.route({ method: 'GET', path: '/', handler: () => 'ok' });
await server.start();

Critical Rules

1. Compose with decorations & methods - Expose services via decorations and reusable logic via methods
2. Follow the lifecycle - 24-step request flow; see lifecycle overview
3. Auth is three layers - scheme → strategy → default; see server auth
4. Validate at the route - Use joi schemas on params, query, payload, headers; see validation
5. Type routes with Refs - Use ServerRoute<Refs> with ONLY the keys you need (Params, Query, Payload, etc.); omitted keys keep defaults. See route scaffold

Auth three-layer pattern:

server.auth.scheme('custom', schemeImpl);     // 1. scheme (how to authenticate)
server.auth.strategy('session', 'custom', options); // 2. strategy (configured instance)
server.auth.default('session');                // 3. default (apply to all routes)

Scheme authenticate MUST return h.authenticated() with both credentials AND artifacts:

return h.authenticated({
    credentials: { user: { id, name }, scope: ['user'] },
    artifacts: { token }       // always include artifacts for raw auth data
});