`ScalarUiOptions` — Zod-validated configuration

(no submodules)

Purpose

The options module owns the single Zod schema consumed by every Scalar UI handler factory. It is exposed both directly (scalarUiOptionsSchema) and via the convenience parseScalarUiOptions(input) helper that wraps the underlying ZodError in an OpenapiUiScalarError tagged with OPENAPI_UI_SCALAR.INVALID_OPTIONS. This double-surface lets host config ingestion decide whether to surface raw Zod issues or rely on the package's stable error-code contract.

Features

Required openapiUrl field (with default /openapi.json).
Endpoint defaults match design doc §7 (/docs/ui/scalar).
Eleven built-in theme literals matching the upstream Scalar palette.
layout literals "modern" | "classic".
assetMode literals "cdn" | "bundled" toggling the runtime asset resolution path.
cdnUrl defaults to the upstream JSDelivr URL of @scalar/api-reference.
editorOptions is an open passthrough bag for upstream Scalar config options the schema does not enumerate.
.strict() rejects unknown keys so typos surface at host-config load.

Usage: Basic

import { parseScalarUiOptions } from "@suaveplan/api-openapi-ui-scalar/options";

const opts = parseScalarUiOptions({ openapiUrl: "/openapi.json" });
console.log(opts.uiEndpoint); // "/docs/ui/scalar"

Usage: Advanced

import {
    parseScalarUiOptions,
    scalarUiOptionsSchema,
} from "@suaveplan/api-openapi-ui-scalar/options";

// Schema can be composed with host-config layers — every default is
// safe in the empty-object case so the schema can be merged with other
// host config without surprises.
const hostSchema = scalarUiOptionsSchema.extend({
    enabled: scalarUiOptionsSchema.shape.darkMode,
});

const parsed = parseScalarUiOptions({
    openapiUrl: "/v1/openapi.json",
    theme: "deepSpace",
    layout: "classic",
    assetMode: "bundled",
});

API Reference

scalarUiOptionsSchema — Zod object schema, .strict().
parseScalarUiOptions(input?) — returns the resolved ScalarUiOptions or throws OpenapiUiScalarError(INVALID_OPTIONS).
SCALAR_THEMES / SCALAR_LAYOUTS / SCALAR_ASSET_MODES — literal unions backing the schema enums.
ScalarUiOptions / ScalarUiOptionsInput — output / input types.

Implementation Notes

The schema uses Zod .default() on every optional field so the empty {} case round-trips to a complete options object. The .strict() mode is essential — host operators frequently mistype keys (e.g. themes vs theme) and the strict guard surfaces those at boot rather than at first request. INVALID_OPTIONS wraps safeParse failures so the error chain preserves the underlying issue list for log/telemetry consumers.

2.8 KiB Raw Blame History

ScalarUiOptions — Zod-validated configuration