Hapi
Quick Start
const server = Hapi.server({ port: 3000 }); server.route({ method: 'GET', path: '/', handler: () => 'ok' }); await server.start();
Critical Rules
- Compose with decorations & methods - Expose services via decorations and reusable logic via methods
- Follow the lifecycle - 24-step request flow; see lifecycle overview
- Auth is three layers - scheme → strategy → default; see server auth
- Validate at the route - Use joi schemas on params, query, payload, headers; see validation
- 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
- Create server - server overview for constructor options
- Register plugins - plugins and plugin structure
- Configure auth - auth schemes and route auth
- Verify auth - Test with
server.inject()before defining protected routes; see network - Define routes - route overview with handlers
- 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 |
