hapi-scalar

A Hapi plugin that serves Scalar API documentation UI for your Hapi server. It provides a modern, interactive OpenAPI/Swagger documentation interface that can be used standalone or alongside hapi-swagger.

Features

• Serves the beautiful Scalar UI at a configurable route (default: /scalar)
• Auto-detects and integrates with hapi-swagger configurations
• Supports both static and dynamic configuration
• TypeScript support

Installation

npm install hapi-scalar

Quick Start

Standalone Usage

import Hapi from '@hapi/hapi'
import hapiScalar from 'hapi-scalar'

const server = Hapi.server({
  port: 3000,
  host: 'localhost',
})

await server.register({
  plugin: hapiScalar,
  options: {
    scalarConfig: {
      url: '/path/to/your/openapi.json', // Your OpenAPI spec URL
    },
  },
})

await server.start()
console.log('Documentation available at: http://localhost:3000/scalar')

Visit http://localhost:3000/scalar to view the Scalar UI.

With hapi-swagger

When used with hapi-swagger, the plugin automatically detects your OpenAPI/Swagger configuration:

import Hapi from '@hapi/hapi'
import Inert from '@hapi/inert'
import Vision from '@hapi/vision'
import HapiSwagger from 'hapi-swagger'
import hapiScalar from 'hapi-scalar'

const server = Hapi.server({
  port: 3000,
  host: 'localhost',
})

// Configure hapi-swagger
const swaggerOptions = {
  info: {
    title: 'My API Documentation',
    version: '1.0.0',
    description: 'This is my awesome API',
  },
  OAS: 'v3.0', // Use OpenAPI 3.0
}

// Register dependencies and hapi-swagger
await server.register([
  Inert,
  Vision,
  { plugin: HapiSwagger, options: swaggerOptions },
])

// Register hapi-scalar - it will automatically use the OpenAPI spec from hapi-swagger
await server.register({
  plugin: hapiScalar,
  options: {
    // Optional: customize the documentation route
    routePrefix: '/docs',
    // Optional: customize Scalar UI
    scalarConfig: {
      hideClientButton: false,
      theme: 'purple',
    },
  },
})

await server.start()
console.log('API Documentation available at: http://localhost:3000/docs')

Note: When hapi-swagger is registered, hapi-scalar automatically uses /openapi.json if OAS is 'v3.0', otherwise /swagger.json. You don’t need to set scalarConfig.url manually.

Configuration Options

Plugin Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | routePrefix | string | '/scalar' | The path where the Scalar documentation UI will be served. | | scalarConfig | object \| function(request) => object \| Promise<object> | {} | Configuration passed to the Scalar UI. Can be a static object or a dynamic function that receives the Hapi request. |

Example:

await server.register({
  plugin: hapiScalar,
  options: {
    routePrefix: '/docs',           // → http://localhost:3000/docs
    scalarConfig: { /* ... */ },    // Scalar UI configuration
  },
})

The scalarConfig object supports all Scalar configuration options.

Dynamic Configuration

Use a function to provide dynamic configuration based on the request:

options: {
  scalarConfig: (request) => {
    return { 
      theme: request.query.theme ?? 'default',
      hideClientButton: true
    }
  }
}

// You can also return a Promise or use an async function:
options: {
  scalarConfig: async (request) => {
    // e.g., fetch from a database or remote config service
    const url = request.query.specUrl || '/openapi.json'
    return { url }
  },
}

TypeScript

Type definitions are included. Example:

import Hapi from '@hapi/hapi'
import hapiScalar from 'hapi-scalar'

const options: hapiScalar.RegisterOptions = {
  routePrefix: '/scalar',
  scalarConfig: {
    url: '/openapi.json',
    hideClientButton: true,
  },
}

await server.register({
  plugin: hapiScalar,
  options,
})

Contributing

Contributions are welcome. Please open an issue or pull request.

License

MIT

Related Projects

• Scalar - The beautiful API documentation UI
• hapi-swagger - Swagger/OpenAPI plugin for Hapi
• @hapi/hapi - The Hapi web framework