# 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.

- Skill: `damusix/hapi` (Agent Skill, multi-file: 61 files)
- Install (CLI): `npx skillmds@latest add damusix/hapi`
- Raw SKILL.md: https://api.skillmd.com/api/skills/damusix/hapi/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: damusix (https://skillmd.com/u/damusix)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/damusix/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](reference/server/decorations.md) and reusable logic via [methods](reference/server/methods.md)
2. **Follow the lifecycle** - 24-step request flow; see [lifecycle overview](reference/lifecycle/overview.md)
3. **Auth is three layers** - scheme → strategy → default; see [server auth](reference/server/auth.md)
4. **Validate at the route** - Use joi schemas on params, query, payload, headers; see [validation](reference/route/validation.md)
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](reference/typescript/route-scaffold.md)

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](reference/server/overview.md) for constructor options
2. **Register plugins** - [plugins](reference/server/plugins.md) and [plugin structure](reference/plugins/overview.md)
3. **Configure auth** - [auth schemes](reference/server/auth.md) and [route auth](reference/route/auth.md)
4. **Verify auth** - Test with `server.inject()` before defining protected routes; see [network](reference/server/network.md)
5. **Define routes** - [route overview](reference/route/overview.md) with [handlers](reference/route/handler.md)
6. **Add extensions** - [lifecycle hooks](reference/server/extensions.md) and [pre-handlers](reference/route/pre.md)


## Key Patterns

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