Hapi

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