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
});

Route validation pattern:

server.route({
    method: 'POST',
    path: '/users',
    options: {
        validate: {
            payload: Joi.object({
                name: Joi.string().required(),
                email: Joi.string().email().required()
            })
        }
    },
    handler: (request) => request.payload
});

Workflow

1. Create server - server overview for constructor options
2. Register plugins - plugins and plugin structure
3. Configure auth - auth schemes and route auth
4. Verify auth - Test with server.inject() before defining protected routes; see network
5. Define routes - route overview with handlers
6. Add extensions - lifecycle hooks and pre-handlers

Key Patterns

| Topic | Reference | | ------------------------ | ------------------------------------------------------------------------------------------------------ | | Request/response objects | request, response | | Response toolkit (h) | toolkit | | Sessions (yar) | sessions | | Caching & CORS | cache-cors, server cache, catbox-memory engine, catbox-fs engine, catbox-redis engine | | Security headers | security | | Payload parsing | payload | | Decorations & methods | decorations, methods | | MIME types (mimos) | mimos | | Realms & plugin scoping | realm | | Response marshalling | marshal pipeline | | File serving (inert) | overview, file handler, directory handler | | Basic authentication | basic auth | | Error handling (Boom) | boom errors | | Error filtering (Bounce) | bounce utility | | WebSockets (nes) | overview, subscriptions, client | | SSE (sse) | overview, api, subscriptions, session, replay | | Startup & shutdown | startup lifecycle | | Events | events | | Testing (server.inject) | network | | TypeScript overview | typescript | | TypeScript auth typing | auth-scheme, type-author | | JWT authentication | jwt overview, validate function, token API | | TypeScript plugins | plugin-scaffold | | Views & templates | vision overview, engines, context & layouts |