alonso-skills/hapi
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.
76
Quality
95%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Securityby
Passed
No known issues
SKILL.md
- 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
- 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 |