Write a custom provider

How-to guide

A provider receives the typed questions of all rules for a page and returns an answer for each. This guide writes a provider for an in-house service that rates documentation, to show the mechanics.

If your service implements the OpenAI chat completions API, use openaiCompatible() instead.

Prerequisites

A Starlight site with Compass and a provider set up.
An API that can answer yes-or-no, multiple choice or scoring questions with probabilities.

Write the provider

Create a function returning a CompassProvider. createClient() returns undefined while the provider is not configured, and Compass logs the setupHint:

import type { CompassProvider, CompassResponse } from "starlight-compass";

export function inHouse(): CompassProvider {
  return {
    name: "in-house",
    setupHint: "Set the `IN_HOUSE_TOKEN` environment variable.",
    createClient({ env }) {
      const token = env["IN_HOUSE_TOKEN"];
      if (!token) return;

      return {
        id: "in-house/v1",
        async ask({ questions, state }) {
          const response = await fetch("https://ratings.example.com/answer", {
            body: JSON.stringify({ questions, state }),
            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
            method: "POST",
          });
          if (!response.ok) throw new Error(`The service responded with ${response.status}.`);

          return (await response.json()) as CompassResponse;
        },
      };
    },
  };
}

Return an answer for every key of questions, in the shape of its question type. The id is part of the cache key, so change it when your service changes how it answers.

Use the provider in your configuration:

import { inHouse } from "./compass-provider";

starlight({
  plugins: [starlightCompass({ provider: inHouse() })],
});

Open a page and check that the Compass window of the dev toolbar shows results.

Compass sends the questions of all rules in a single request and caches the responses, so ask() runs once per changed page.

The ask option only supports the built-in providers. To let readers ask the docs with a custom provider, use the manual setup.