@scalar/starlight 0.2.0

package/README.md

@@ -0,0 +1,74 @@
+# Scalar API Reference for Astro Starlight
+
+[![Version](https://img.shields.io/npm/v/@scalar/starlight)](https://www.npmjs.com/package/@scalar/starlight)
+[![Downloads](https://img.shields.io/npm/dm/@scalar/starlight)](https://www.npmjs.com/package/@scalar/starlight)
+[![License](https://img.shields.io/npm/l/@scalar/starlight)](https://www.npmjs.com/package/@scalar/starlight)
+[![Discord](https://img.shields.io/discord/1135330207960678410?style=flat&color=5865F2)](https://discord.gg/scalar)
+
+A [Starlight](https://starlight.astro.build) plugin that renders a beautiful Scalar API reference from an OpenAPI document, inside your Starlight docs.
+
+## Installation
+
+```bash
+npm install @scalar/starlight
+```
+
+## Usage
+
+Add the plugin to your Starlight configuration and point it at an OpenAPI document. It injects a route that renders the API reference inside the Starlight layout and adds a sidebar entry that links to it — no need to hand-create a page.
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
+import starlight from '@astrojs/starlight'
+import { scalarStarlight } from '@scalar/starlight'
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'My Docs',
+      plugins: [
+        scalarStarlight({
+          // Scalar's universal configuration object:
+          // https://scalar.com/products/api-references/configuration
+          configuration: {
+            url: '/openapi.json',
+          },
+        }),
+      ],
+    }),
+  ],
+})
+```
+
+The reference is served from `/api-reference` by default.
+
+> [!NOTE]
+> If you do not define a `sidebar` in your Starlight config, Starlight auto-generates it from your docs. In that case the plugin does not add the entry (doing so would replace the auto-generated sidebar and hide your other pages) and logs a note instead — add the link yourself, e.g. `sidebar: [{ label: 'API Reference', link: '/api-reference' }]`.
+
+## Options
+
+| Option          | Default            | Description                                                                                     |
+| --------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
+| `configuration` | —                  | Scalar's universal [configuration object](https://scalar.com/products/api-references/configuration). |
+| `pathname`      | `'/api-reference'` | The path the API reference is served from.                                                      |
+| `label`         | `'API Reference'`  | The label of the sidebar entry.                                                                 |
+| `title`         | the `label`        | The title of the API reference page.                                                            |
+
+## Multiple references
+
+Add the plugin more than once, each with its own `pathname`, to serve several API references from one site:
+
+```js
+plugins: [
+  scalarStarlight({ pathname: '/reference/payments', label: 'Payments', configuration: { url: '/payments.json' } }),
+  scalarStarlight({ pathname: '/reference/billing', label: 'Billing', configuration: { url: '/billing.json' } }),
+]
+```
+
+> [!NOTE]
+> The configuration is serialized into the page as JSON, so function-valued options (a custom `fetch`, `onLoaded`, plugins, …) are not carried over. This mirrors the `renderMode="client"` behavior of [`@scalar/astro`](https://www.npmjs.com/package/@scalar/astro), which this plugin builds on so the reference keeps working across Starlight's client-side navigation.
+
+## License
+
+The source code in this repository is licensed under [MIT](https://github.com/scalar/scalar/blob/main/LICENSE).

package/index.ts

@@ -0,0 +1,10 @@
+// Do not write code directly here, instead use the `src` folder!
+// Then, use this file to export everything you want your user to access.
+
+import { scalarStarlight } from './src/plugin'
+
+export { scalarStarlight }
+
+export type { ScalarStarlightOptions } from './src/plugin'
+
+export default scalarStarlight

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@scalar/starlight",
+  "description": "Scalar API Reference plugin for Astro Starlight",
+  "license": "MIT",
+  "author": "Scalar (https://github.com/scalar)",
+  "homepage": "https://github.com/scalar/scalar",
+  "bugs": "https://github.com/scalar/scalar/issues/new/choose",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scalar/scalar.git",
+    "directory": "integrations/starlight"
+  },
+  "keywords": [
+    "astro-component",
+    "starlight",
+    "starlight-plugin",
+    "scalar",
+    "openapi",
+    "swagger"
+  ],
+  "version": "0.2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "cd playground && pnpm dev",
+    "test": "vitest --run"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "index.ts"
+  ],
+  "scalarReadme": {
+    "title": "Scalar API Reference for Astro Starlight",
+    "badges": [
+      {
+        "type": "npm-version"
+      },
+      {
+        "type": "npm-downloads"
+      },
+      {
+        "type": "npm-license"
+      }
+    ],
+    "documentation": "https://scalar.com/products/api-references/integrations/starlight"
+  },
+  "dependencies": {
+    "@scalar/astro": "workspace:*",
+    "@scalar/client-side-rendering": "workspace:*"
+  },
+  "devDependencies": {
+    "@astrojs/starlight": "catalog:*",
+    "astro": "catalog:*"
+  },
+  "peerDependencies": {
+    "@astrojs/starlight": ">=0.32.0",
+    "astro": "^5.0.0 || ^6.0.0"
+  }
+}

package/src/ScalarReference.astro

@@ -0,0 +1,43 @@
+---
+import { ScalarComponent } from '@scalar/astro'
+import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro'
+
+import { references } from 'virtual:scalar-starlight'
+
+import { normalizePathname } from './normalize-pathname'
+
+// One route module renders every configured reference, so pick the entry that
+// matches this page. Strip Astro's `base` from the request path and normalize it
+// with the same helper the plugin used for each `pathname`, so the key lines up
+// regardless of `base` or trailing-slash settings.
+const base = import.meta.env.BASE_URL
+const relative = Astro.url.pathname.startsWith(base) ? Astro.url.pathname.slice(base.length) : Astro.url.pathname
+const key = normalizePathname(relative)
+
+// Fall back to the only entry when there is a single reference (the common
+// case), which keeps things working even if the path ever fails to match. With
+// several references a miss cannot be resolved safely — silently rendering the
+// first one would show the wrong API — so fail loudly instead.
+const entries = Object.values(references)
+const reference = references[key] ?? (entries.length === 1 ? entries[0] : undefined)
+if (!reference) {
+  throw new Error(
+    `[@scalar/starlight] No API reference is registered for "${key}". ` +
+      `Registered references: ${Object.keys(references).join(', ')}.`,
+  )
+}
+const { configuration, title } = reference
+---
+
+{/*
+  Render the API reference inside the Starlight layout, so it keeps the site
+  header and sidebar. `template: 'splash'` gives the reference the full content
+  width (Scalar brings its own operations sidebar).
+
+  `renderMode="client"` is required here: Starlight ships `<ClientRouter />`, so
+  navigation happens client-side and the static render script would otherwise
+  only run after a manual refresh.
+*/}
+<StarlightPage frontmatter={{ title, template: 'splash' }}>
+  <ScalarComponent renderMode="client" configuration={configuration} />
+</StarlightPage>

package/src/integration.ts

@@ -0,0 +1,115 @@
+import { fileURLToPath } from 'node:url'
+
+import type { HtmlRenderingConfiguration } from '@scalar/client-side-rendering'
+import type { AstroIntegration } from 'astro'
+
+type ScalarReference = {
+  /** The title of the API reference page. */
+  title: string
+  /** The Scalar configuration, passed to the reference. */
+  configuration: Partial<HtmlRenderingConfiguration>
+}
+
+type ScalarRouteOptions = ScalarReference & {
+  /** The normalized path the API reference is served from. */
+  pathname: string
+}
+
+/** The virtual module the injected route reads its configuration from. */
+const VIRTUAL_ID = 'virtual:scalar-starlight'
+const RESOLVED_VIRTUAL_ID = `\0${VIRTUAL_ID}`
+
+/**
+ * Every reference on the site, keyed by its normalized `pathname`.
+ *
+ * A single bundled `.astro` component renders all of them, and a bundled
+ * component cannot receive per-instance props. So instead of one virtual module
+ * per reference (they would all resolve the same id and only the first would
+ * win), we collect every reference here and let the component pick its own by
+ * matching the request path at render time. This is what lets one site expose
+ * several references at once.
+ *
+ * The registry lives at module scope so it is shared across every
+ * `scalarStarlight()` instance in a single Astro config.
+ */
+const references = new Map<string, ScalarReference>()
+
+/**
+ * The subset of a Vite plugin this integration uses.
+ *
+ * Astro bundles its own Vite (currently v6), while the workspace catalog pins a
+ * newer Vite whose `Plugin` type is not structurally identical. Describing just
+ * the hooks used here keeps the plugin assignable to whichever Vite Astro ships,
+ * without importing (and thereby version-locking) Vite's `Plugin` type.
+ */
+type VirtualModulePlugin = {
+  name: string
+  resolveId: (id: string) => string | undefined
+  load: (id: string) => string | undefined
+}
+
+/**
+ * A Vite plugin that exposes every reference to the injected `.astro` route.
+ *
+ * The route is a bundled component, so it cannot receive props from the plugin
+ * directly. Serializing the registry into a virtual module is the standard way
+ * to hand data to injected routes. `load` reads the registry lazily — it runs at
+ * build time, after every instance has registered, so it sees them all.
+ */
+const virtualConfigurationPlugin = (): VirtualModulePlugin => ({
+  name: '@scalar/starlight:virtual-configuration',
+  resolveId: (id: string): string | undefined => (id === VIRTUAL_ID ? RESOLVED_VIRTUAL_ID : undefined),
+  load: (id: string): string | undefined =>
+    id === RESOLVED_VIRTUAL_ID
+      ? `export const references = ${JSON.stringify(Object.fromEntries(references))}`
+      : undefined,
+})
+
+/**
+ * The Astro integration that renders the API reference.
+ *
+ * It registers the reference, injects a route at `pathname` pointing at the
+ * bundled `ScalarReference` component, and exposes the registry through a
+ * virtual module that feeds every reference its configuration.
+ */
+export const scalarRouteIntegration = (options: ScalarRouteOptions): AstroIntegration => {
+  const reference = { title: options.title, configuration: options.configuration }
+
+  // Two references sharing a `pathname` would inject the same route twice and
+  // surface only as an opaque Astro duplicate-route error, so fail early with a
+  // message that points at the cause. Registering the *same* reference again is
+  // fine (a dev-server config reload re-runs this), so only reject a genuine
+  // collision — a different reference on a pathname already taken.
+  const existing = references.get(options.pathname)
+  if (existing && JSON.stringify(existing) !== JSON.stringify(reference)) {
+    throw new Error(
+      `[@scalar/starlight] Two different API references are configured for "${options.pathname}". ` +
+        'Give each reference a distinct `pathname`.',
+    )
+  }
+
+  references.set(options.pathname, reference)
+
+  return {
+    // Unique per `pathname` so Astro treats multiple references as distinct
+    // integrations. A shared name risks Astro skipping all but the first, which
+    // would drop every reference except one.
+    name: `@scalar/starlight:${options.pathname}`,
+    hooks: {
+      'astro:config:setup': ({ injectRoute, updateConfig }) => {
+        updateConfig({
+          vite: {
+            plugins: [virtualConfigurationPlugin()],
+          },
+        })
+
+        injectRoute({
+          pattern: options.pathname,
+          // The package ships its source, so this resolves to the `.astro` file
+          // inside `node_modules`.
+          entrypoint: fileURLToPath(new URL('./ScalarReference.astro', import.meta.url)),
+        })
+      },
+    },
+  }
+}

package/src/normalize-pathname.ts

@@ -0,0 +1,15 @@
+/**
+ * Ensure the path starts with a single leading slash and has no trailing slash,
+ * so it works both as an Astro route pattern and as a Starlight sidebar link.
+ *
+ * Splitting on `/` rather than trimming with a regex keeps this linear and
+ * sidesteps the backtracking a `/+` pattern can cause on adversarial input. It
+ * also collapses empty segments (e.g. from `//`), which Astro route patterns
+ * would reject anyway.
+ *
+ * This lives in its own module because both the plugin (when registering a
+ * reference) and the route component (when matching the request path back to a
+ * reference) must normalize identically — if the two ever drifted, lookups
+ * would silently miss and render the wrong reference.
+ */
+export const normalizePathname = (pathname: string): string => `/${pathname.split('/').filter(Boolean).join('/')}`

package/src/plugin.ts

@@ -0,0 +1,104 @@
+import type { StarlightPlugin } from '@astrojs/starlight/types'
+import type { HtmlRenderingConfiguration } from '@scalar/client-side-rendering'
+
+import { scalarRouteIntegration } from './integration'
+import { normalizePathname } from './normalize-pathname'
+
+export type ScalarStarlightOptions = {
+  /**
+   * The Scalar configuration.
+   *
+   * This is Scalar's universal configuration object, most importantly the
+   * `url` (or `content`) of the OpenAPI document to render. See
+   * https://scalar.com/products/api-references/configuration for the full list.
+   *
+   * The configuration is serialized into the page as JSON, so function-valued
+   * options (a custom `fetch`, `onLoaded`, plugins, …) are not carried over.
+   */
+  configuration: Partial<HtmlRenderingConfiguration>
+  /**
+   * The path the API reference is served from.
+   *
+   * @default '/api-reference'
+   */
+  pathname?: string
+  /**
+   * The label of the sidebar entry that links to the API reference.
+   *
+   * @default 'API Reference'
+   */
+  label?: string
+  /**
+   * The title of the API reference page.
+   *
+   * @default the `label`
+   */
+  title?: string
+}
+
+/**
+ * A Starlight plugin that renders a Scalar API reference.
+ *
+ * It injects a route that renders the API reference inside the Starlight layout
+ * and adds a sidebar entry that links to it, so you do not have to hand-create a
+ * page and embed the component yourself.
+ *
+ * @example
+ * ```js
+ * // astro.config.mjs
+ * import starlight from '@astrojs/starlight'
+ * import { scalarStarlight } from '@scalar/starlight'
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     starlight({
+ *       title: 'My Docs',
+ *       plugins: [scalarStarlight({ configuration: { url: '/openapi.json' } })],
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export const scalarStarlight = (options: ScalarStarlightOptions): StarlightPlugin => {
+  const pathname = normalizePathname(options.pathname ?? '/api-reference')
+
+  // A `pathname` that normalizes to the site root would collide with the
+  // homepage and only surface as an opaque Astro duplicate-route error, so fail
+  // early with a message that points at the actual cause.
+  if (pathname === '/') {
+    throw new Error(
+      '[@scalar/starlight] `pathname` must not resolve to "/", which would collide with your homepage. ' +
+        'Use a subpath like "/api-reference".',
+    )
+  }
+
+  const label = options.label ?? 'API Reference'
+  const title = options.title ?? label
+
+  return {
+    name: '@scalar/starlight',
+    hooks: {
+      'config:setup': ({ config, updateConfig, addIntegration, logger }) => {
+        // Inject the route that renders the reference. Starlight plugins cannot
+        // inject routes directly, so this goes through an Astro integration.
+        addIntegration(scalarRouteIntegration({ pathname, title, configuration: options.configuration }))
+
+        // Only touch the sidebar when the user already defines one. If it is
+        // left undefined, Starlight auto-generates the sidebar from the docs
+        // directory — replacing it with a single entry would hide every other
+        // page, so we leave it alone and tell the user how to add the link.
+        if (config.sidebar) {
+          updateConfig({
+            sidebar: [...config.sidebar, { label, link: pathname }],
+          })
+        } else {
+          logger.warn(
+            `No \`sidebar\` is configured, so Starlight auto-generates it from your docs and the "${label}" ` +
+              'entry was not added (adding it would hide your other pages). Add it yourself, e.g. ' +
+              `\`sidebar: [{ label: '${label}', link: '${pathname}' }]\`, or link to ${pathname} from your content.`,
+          )
+        }
+      },
+    },
+  }
+}

package/src/virtual.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The virtual module the injected `ScalarReference.astro` route reads its
+ * configuration from. It is generated at build time by `integration.ts`.
+ *
+ * `references` holds every configured reference keyed by its normalized
+ * `pathname`, so the shared route component can pick the one that matches the
+ * page being rendered.
+ */
+declare module 'virtual:scalar-starlight' {
+  import type { HtmlRenderingConfiguration } from '@scalar/client-side-rendering'
+
+  export const references: Record<string, { configuration: Partial<HtmlRenderingConfiguration>; title: string }>
+}