Scalar

Interactive API documentation with Scalar API Reference

By default, SchemaPlugin serves Scalar API Reference at GET /_schema/docs. Scalar reads your live OpenAPI document from /_schema/ and renders a modern, interactive UI (try requests, browse models, multiple themes).

No separate Express/Fastify adapter is required - Vercube uses @scalar/client-side-rendering to return a self-contained HTML page that loads Scalar from a CDN.

Default behavior

After app.addPlugin(SchemaPlugin):

EndpointDescription
/_schema/OpenAPI 3.0 JSON (SchemaRegistry.generateSchema())
/_schema/docsScalar HTML UI pointing at /_schema/

Open http://localhost:<port>/_schema/docs while your app is running.

Configuration

Pass options as the second argument to addPlugin or via withPluginOptions:

import { createApp, withPluginOptions } from '@vercube/core';
import { SchemaPlugin } from '@vercube/schema';

const app = await createApp({
  setup: async (app) => {
    app.addPlugin(
      SchemaPlugin,
      {
        scalar: {
          pageTitle: 'Acme API',
          openApiUrl: '/_schema/',
          config: {
            theme: 'purple',
          },
        },
      },
    );
  },
});
vercube.config.ts
import { defineConfig, withPluginOptions } from '@vercube/core';
import { SchemaPlugin } from '@vercube/schema';

export default defineConfig({
  plugins: [
    withPluginOptions(SchemaPlugin, {
      scalar: { pageTitle: 'Acme API' },
    }),
  ],
});

SchemaPluginOptions

OptionTypeDefaultDescription
scalarfalse | SchemaScalarOptionsenabledSet to false to disable the docs route

SchemaScalarOptions

OptionTypeDefaultDescription
openApiUrlstring'/_schema/'URL Scalar fetches for the OpenAPI document
pageTitlestring'API Reference'HTML <title>
cdnstringScalar default (jsDelivr)CDN URL for the @scalar/api-reference bundle
configPartial<HtmlRenderingConfiguration>-Extra Scalar settings (theme, layout, etc.)

config accepts the same options as Scalar’s API Reference configuration (for example theme, custom CSS, multiple sources).

Disable Scalar

Keep OpenAPI JSON, hide the UI:

app.addPlugin(SchemaPlugin, { scalar: false });

GET /_schema/docs then returns 404.

Custom OpenAPI URL

If you proxy the spec or mount the app under a prefix, point Scalar at the correct spec URL:

app.addPlugin(SchemaPlugin, {
  scalar: {
    openApiUrl: '/api/v1/_schema/',
  },
});

The path must match where SchemaController is actually served (controller base path is /_schema unless you change it in the framework).

Behind reverse proxies

Use an absolute or root-relative openApiUrl that the browser can reach, not an internal hostname. For example:

scalar: {
  openApiUrl: 'https://api.example.com/_schema/',
}

Types

Exported from @vercube/schema:

import type { SchemaPluginOptions, SchemaScalarOptions } from '@vercube/schema';
Report an issue or Edit this page on GitHub
Previous

Overview

Use Vercube controllers and DI inside a Nitro application - experimental

Next