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

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