Branded API Docs Without Losing the Contract: Customizing Scalar in DaloyJS

# The Slack thread that started this feature, only lightly fictionalised:
#
# - Marketing:  "Can the /docs page use our brand colours? It looks like
#                a stranger's house. We have a design system."
# - PM:         "Can we hide the Try-It button on prod? An enterprise
#                customer 'tested' DELETE /v1/accounts/:id last Tuesday."
# - Security:   "And the favicon. It has to come from our CDN. CSP."
# - You:        "Sure, I'll just fork the docs route."
#
# Six weeks later: there is a 200-line bespoke /docs handler that hard-codes
# the spec URL. The spec URL is "/openapi-v1.json". The new route the team
# shipped this morning is at "/openapi.json". Guess which one the docs page
# is rendering.
#
# This is the part of the job that should not be a project.

// src/app.ts — before. Defaults are fine, but you cannot say "and also
// hide the Try It button on prod" without leaving the constructor.
import { App } from "@daloyjs/core";

export const app = new App({
  docs: "auto",  // mounts /docs and /openapi.json, generic Scalar theme.
});

// src/app.ts — after. New in 0.14: docs.scalar accepts any JSON-serialisable
// option the Scalar API reference understands.
import { App } from "@daloyjs/core";

export const app = new App({
  docs: {
    path: "/docs",
    openapiPath: "/openapi.json",
    ui: "scalar",
    scalar: {
      theme: "deepSpace",
      layout: "modern",
      hideTestRequestButton: process.env.NODE_ENV === "production",
      hideClientButton: false,
      hideDarkModeToggle: false,
      showOperationId: true,
      defaultOpenFirstTag: true,
      favicon: "/static/brand/favicon.svg",
      customCss: `
        :root {
          --scalar-color-1: #0b1020;
          --scalar-color-accent: #ff6a3d;
          --scalar-font: "Inter", system-ui, sans-serif;
        }
      `,
    },
  },
});

// src/docs.ts — what Daloy does at serialize time. (Excerpt; the real
// code is in @daloyjs/core/src/docs.ts and the contract is enforced by
// the ScalarReferenceConfiguration type.)
//
// Everything that points Scalar at a *different* spec is stripped here,
// and 'url' is force-set to the live OpenAPI route the App is already
// serving. No matter what you pass, the rendered docs page reads the
// same spec your typed client and contract tests read.
const STRIP_RUNTIME_FIELDS = [
  "content",       // inline spec — would shadow the live route
  "sources",       // multi-spec switcher — silently picks the wrong one
  "spec",          // deprecated alias of content
  "url",           // we ALWAYS set this ourselves
  "plugins",       // functions — not JSON-serialisable
  "fetch",         // function — not JSON-serialisable
] as const;

// And these are typed as 'never' so TypeScript catches you before you
// even try. Functions can't ride along inside a data-* attribute, and
// pretending they can would be a fun footgun:
//
//   onBeforeRequest?: never;
//   generateOperationSlug?: never;
//   redirect?: never;
//   ...

const safe = stripRuntimeFields(scalar);
const finalConfig = { ...safe, url: openapiPath };  // <-- always wins
const dataAttr = ` data-configuration='${escapeHtml(JSON.stringify(finalConfig))}'`;

// You try to be clever. TypeScript stops you.
export const app = new App({
  docs: {
    scalar: {
      theme: "deepSpace",
      onBeforeRequest: (req) => {           // <-- red squiggle here
        req.headers.set("x-debug", "1");
      },
      sources: [                            // <-- and here
        { url: "/openapi-experimental.json", title: "Beta" },
      ],
    },
  },
});

// tsc says, with the patience of an older sibling:
//
//   Type '(req: Request) => void' is not assignable to type 'never'.
//   Type '{ url: string; title: string; }[]' is not assignable to type 'never'.
//
// Translation: that field can't ride inside data-configuration. Use
// scalarHtml({ configuration }) directly on a custom route if you need it.

<!-- The single line that lands in the browser. Yes, just one script tag
     and one data attribute. Scalar's HTML API does the rest. -->
<script
  id="api-reference"
  data-url="/openapi.json"
  data-configuration='{"theme":"deepSpace","layout":"modern","hideTestRequestButton":true,"showOperationId":true,"defaultOpenFirstTag":true,"favicon":"/static/brand/favicon.svg","customCss":":root{--scalar-color-1:#0b1020;--scalar-color-accent:#ff6a3d;}","url":"/openapi.json"}'>
</script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>

// One pattern I use a lot: dev gets all the toys, prod gets the brand
// chrome and nothing dangerous. No NODE_ENV ifs inside the template,
// no fork of the docs route. Just two configs.
import { App, type ScalarReferenceConfiguration } from "@daloyjs/core";

const isProd = process.env.NODE_ENV === "production";

const scalar: ScalarReferenceConfiguration = isProd
  ? {
      theme: "deepSpace",
      layout: "modern",
      hideTestRequestButton: true,
      hideClientButton: true,
      showDeveloperTools: "never",
      defaultOpenFirstTag: true,
      customCss: brandCss,
    }
  : {
      theme: "kepler",
      layout: "modern",
      showDeveloperTools: "always",
      defaultOpenAllTags: true,
      expandAllResponses: true,
      persistAuth: true,
    };

export const app = new App({
  docs: { ui: "scalar", scalar },
});

// You need a function-valued option (a plugin, an onBeforeRequest hook,
// a custom slug generator). docs.scalar can't carry those — they're not
// JSON-serialisable, and shoving a stringified function into a data-*
// attribute is the kind of thing you read about in incident reviews.
//
// Drop the auto-mount and use scalarHtml() directly. Same generator,
// same CSP, same nonce handling — just rendered by a route you control.
import { App, scalarHtml, htmlResponse } from "@daloyjs/core";

export const app = new App({ docs: false });

app.get("/docs", (ctx) => {
  // scalarHtml() takes the same configuration shape, but here you can
  // also assemble the page yourself (extra <link>, an extra <script>
  // that registers a Scalar plugin, etc).
  const html = scalarHtml({
    specUrl: "/openapi.json",
    title: "Bookstore API",
    scriptNonce: ctx.state.cspNonce,   // works with secureHeaders() CSP
    configuration: {
      theme: "deepSpace",
      layout: "modern",
      customCss: brandCss,
    },
  });
  return htmlResponse(html, { scriptNonce: ctx.state.cspNonce });
});

// tests/docs-scalar.test.ts — the regression test I copy into every
// project. Two lines, catches the next intern who hard-codes a different
// spec URL into the rendered HTML "just for debugging."
import { test } from "node:test";
import assert from "node:assert/strict";
import { app } from "../src/app.ts";

test("docs page renders Scalar with our brand config", async () => {
  const res = await app.request("/docs");
  const body = await res.text();

  assert.equal(res.status, 200);
  assert.match(body, /id="api-reference"/);
  assert.match(body, /"theme":"deepSpace"/);
  assert.match(body, /"hideTestRequestButton":true/);

  // The important one. Daloy must force the live spec URL into the
  // config payload, regardless of what we passed (or didn't pass).
  assert.match(body, /"url":"\/openapi\.json"/);
});

# A short checklist before you ship a branded /docs page.
#
# 1) Pick a theme. There are 12. "default", "deepSpace", "kepler",
#    "moon", "saturn", "purple", "solarized", "laserwave", "alternate",
#    "mars", "bluePlanet", "none". Audition them in dev; they're free.
#
# 2) hideTestRequestButton: true in production unless the docs are
#    behind your internal SSO. The Try-It button is real fetch().
#
# 3) customCss is a string — keep it small. Two or three CSS vars
#    (--scalar-color-1, --scalar-color-accent, --scalar-font) cover
#    90% of brand work. Don't reimplement Tailwind in there.
#
# 4) Don't set 'url', 'content', 'sources', 'spec', 'plugins', or
#    'fetch'. They're either stripped or typed as 'never'. The whole
#    point is that the docs page reads the same spec your client does.
#
# 5) If you need a function-valued option, fall back to scalarHtml()
#    on a route you control. Same CSP, same nonce, same generator.
#
# 6) Snapshot test the rendered page. Two assert.match() calls is
#    enough to catch 'someone broke the brand config' for years.