@scalar/hono-api-reference 0.11.16 → 0.12.0

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export { Scalar,
  * @deprecated Use `Scalar` instead.
  */
 Scalar as apiReference, };
+export type { ServeConfiguration } from './scalar.js';
 export type { ApiReferenceConfiguration } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEjC,OAAO,EACL,MAAM;AACN;;GAEG;AACH,MAAM,IAAI,YAAY,GACvB,CAAA;AAED,YAAY,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AAEjC,OAAO,EACL,MAAM;AACN;;GAEG;AACH,MAAM,IAAI,YAAY,GACvB,CAAA;AAED,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAClD,YAAY,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA"}

package/dist/scalar.d.ts

@@ -1,9 +1,53 @@
 import type { Context, Env, MiddlewareHandler } from 'hono';
+import { Hono } from 'hono';
 import type { ApiReferenceConfiguration } from './types.js';
 type Configuration<E extends Env> = Partial<ApiReferenceConfiguration> | ((c: Context<E>) => Partial<ApiReferenceConfiguration> | Promise<Partial<ApiReferenceConfiguration>>);
 /**
- * The Hono middleware for the Scalar API Reference.
+ * An OpenAPI document.
+ *
+ * Typed loosely as an object on purpose, so it accepts both plain document objects and the typed
+ * return values of generators like Zod OpenAPI Hono's `getOpenAPI31Document()`, whose interfaces do
+ * not carry an index signature.
  */
-export declare const Scalar: <E extends Env>(configOrResolver: Configuration<E>) => MiddlewareHandler<E>;
+type OpenApiDocument = object;
+/**
+ * The configuration for `Scalar.serve`.
+ *
+ * On top of the universal API Reference configuration, this takes the OpenAPI `document` to render
+ * and expose. Because `Scalar.serve` sources the document itself, `content` and `url` are managed for
+ * you and are not accepted here.
+ */
+export type ServeConfiguration<E extends Env> = Omit<Partial<ApiReferenceConfiguration>, 'content' | 'url'> & {
+    /**
+     * The OpenAPI document to render and serve.
+     *
+     * Pass the document directly, or a function that returns it. The function receives the Hono
+     * `Context`, so it can read `c.env` or `c.req` and build the document per request. This is also how
+     * you wire up an `OpenAPIHono` app:
+     *
+     * @example
+     * ```ts
+     * app.route('/scalar', Scalar.serve({
+     *   document: () => app.getOpenAPI31Document({ openapi: '3.1.0', info: { title: 'Example', version: 'v1' } }),
+     * }))
+     * ```
+     */
+    document: OpenApiDocument | ((c: Context<E>) => OpenApiDocument | Promise<OpenApiDocument>);
+    /**
+     * Path, relative to the mount point, where the OpenAPI document is served as JSON.
+     *
+     * @default '/openapi.json'
+     */
+    documentPath?: string;
+};
+/**
+ * Render the Scalar API Reference in a Hono app.
+ *
+ * Use `Scalar(...)` as a middleware to render the reference on a route, or `Scalar.serve(...)` to
+ * serve the reference and its OpenAPI document together from a single mount.
+ */
+export declare const Scalar: (<E extends Env>(configOrResolver: Configuration<E>) => MiddlewareHandler<E>) & {
+    serve: <E extends Env>(options: ServeConfiguration<E>) => Hono<E>;
+};
 export {};
 //# sourceMappingURL=scalar.d.ts.map

package/dist/scalar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAE3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAgExD,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAC5B,OAAO,CAAC,yBAAyB,CAAC,GAClC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAA;AAEzG;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,GAAG,EAAE,kBAAkB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAoB7F,CAAA"}
+{"version":3,"file":"scalar.d.ts","sourceRoot":"","sources":["../src/scalar.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAA;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAA;AAgExD,KAAK,aAAa,CAAC,CAAC,SAAS,GAAG,IAC5B,OAAO,CAAC,yBAAyB,CAAC,GAClC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,yBAAyB,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAA;AA2BzG;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,MAAM,CAAA;AAE7B;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,yBAAyB,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG;IAC5G;;;;;;;;;;;;;OAaG;IACH,QAAQ,EAAE,eAAe,GAAG,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAA;IAC3F;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAgDD;;;;;GAKG;AACH,eAAO,MAAM,MAAM,IAlHO,CAAC,SAAS,GAAG,oBAAoB,aAAa,CAAC,CAAC,CAAC,KAAG,iBAAiB,CAAC,CAAC,CAAC;YA+E7E,CAAC,SAAS,GAAG,WAAW,kBAAkB,CAAC,CAAC,CAAC,KAAG,IAAI,CAAC,CAAC,CAAC;CAmCC,CAAA"}

package/dist/scalar.js

@@ -1,4 +1,5 @@
 import { renderApiReference } from '@scalar/client-side-rendering';
+import { Hono } from 'hono';
 /**
  * The default configuration for the API Reference.
  */
@@ -62,7 +63,7 @@ const customTheme = `
 /**
  * The Hono middleware for the Scalar API Reference.
  */
-export const Scalar = (configOrResolver) => {
+const scalarMiddleware = (configOrResolver) => {
     return async (c) => {
         let resolvedConfig = {};
         if (typeof configOrResolver === 'function') {
@@ -81,3 +82,47 @@ export const Scalar = (configOrResolver) => {
         return c.html(renderApiReference({ config, pageTitle, cdn, nonce }, customTheme));
     };
 };
+/**
+ * Serve the API Reference and its OpenAPI document together as a mountable Hono app.
+ *
+ * Unlike the `Scalar` middleware — which only renders the reference and expects the document to live
+ * somewhere else — this exposes both from a single call, so you do not have to wire up a separate
+ * document route and keep its `url` in sync.
+ *
+ * Mount it with `app.route(...)`:
+ *
+ * @example
+ * ```ts
+ * import { Scalar } from '@scalar/hono-api-reference'
+ *
+ * // Serves the reference at `/scalar` and the document at `/scalar/openapi.json`
+ * app.route('/scalar', Scalar.serve({ document: myOpenApiDocument }))
+ * ```
+ */
+const scalarServe = (options) => {
+    const { document, documentPath = '/openapi.json', ...rest } = options;
+    const app = new Hono();
+    const resolveDocument = (c) => typeof document === 'function' ? document(c) : document;
+    // Expose the OpenAPI document as JSON, so a single call powers both the reference and its source.
+    app.get(documentPath, async (c) => c.json(await resolveDocument(c)));
+    // Render the reference, pointing it at the document we expose above.
+    app.get('/', (c) => {
+        // Build a root-absolute URL to the document from the current request path. This keeps the
+        // reference working wherever it is mounted, and whether or not the request has a trailing slash.
+        const url = `${c.req.path.replace(/\/+$/, '')}${documentPath}`;
+        const { cdn, pageTitle, nonce, ...config } = {
+            ...DEFAULT_CONFIGURATION,
+            ...rest,
+            url,
+        };
+        return c.html(renderApiReference({ config, pageTitle, cdn, nonce }, customTheme));
+    });
+    return app;
+};
+/**
+ * Render the Scalar API Reference in a Hono app.
+ *
+ * Use `Scalar(...)` as a middleware to render the reference on a route, or `Scalar.serve(...)` to
+ * serve the reference and its OpenAPI document together from a single mount.
+ */
+export const Scalar = Object.assign(scalarMiddleware, { serve: scalarServe });

package/dist/scalar.test.js

@@ -206,4 +206,72 @@ describe('Scalar', () => {
         expect(text).toContain('Test API');
         expect(text).toContain('deepSpace');
     });
+    describe('serve', () => {
+        const document = {
+            openapi: '3.1.0',
+            info: { title: 'Serve API', version: '1.0.0' },
+            paths: {},
+        };
+        it('serves the OpenAPI document as JSON at the mount point', async () => {
+            const app = new Hono();
+            app.route('/scalar', Scalar.serve({ document }));
+            const response = await app.request('/scalar/openapi.json');
+            expect(response.status).toBe(200);
+            expect(response.headers.get('content-type')).toContain('application/json');
+            expect(await response.json()).toEqual(document);
+        });
+        it('renders the reference at the mount point, pointing at the served document', async () => {
+            const app = new Hono();
+            app.route('/scalar', Scalar.serve({ document }));
+            const response = await app.request('/scalar');
+            expect(response.status).toBe(200);
+            expect(response.headers.get('content-type')).toContain('text/html');
+            const text = await response.text();
+            expect(text).toContain('<title>Scalar API Reference</title>');
+            // The reference points at the document we serve alongside it
+            expect(text).toContain('/scalar/openapi.json');
+            // The document is referenced by URL, not inlined
+            expect(text).not.toContain('Serve API');
+        });
+        it('serves the document at a custom documentPath', async () => {
+            const app = new Hono();
+            app.route('/scalar', Scalar.serve({ document, documentPath: '/spec.json' }));
+            const json = await app.request('/scalar/spec.json');
+            expect(json.status).toBe(200);
+            expect(await json.json()).toEqual(document);
+            const html = await (await app.request('/scalar')).text();
+            expect(html).toContain('/scalar/spec.json');
+        });
+        it('resolves the document from a function with access to the context', async () => {
+            const app = new Hono();
+            app.route('/scalar', Scalar.serve({
+                document: (c) => ({ ...document, info: { ...document.info, title: c.req.path } }),
+            }));
+            const response = await app.request('/scalar/openapi.json');
+            expect(await response.json()).toMatchObject({ info: { title: '/scalar/openapi.json' } });
+        });
+        it('passes through reference options like pageTitle and theme', async () => {
+            const app = new Hono();
+            app.route('/scalar', Scalar.serve({ document, pageTitle: 'Serve Title', theme: 'kepler' }));
+            const text = await (await app.request('/scalar')).text();
+            expect(text).toContain('<title>Serve Title</title>');
+            // A theme was provided, so the custom Hono theme CSS is not injected
+            expect(text).not.toContain('--scalar-color-1: rgba(255, 255, 245, .86);');
+        });
+        it('includes the hono integration marker and the custom theme by default', async () => {
+            const app = new Hono();
+            app.route('/scalar', Scalar.serve({ document }));
+            const text = await (await app.request('/scalar')).text();
+            expect(text).toContain('_integration": "hono"');
+            expect(text).toContain('--scalar-color-1: rgba(255, 255, 245, .86);');
+        });
+        it('works when mounted at the root', async () => {
+            const app = new Hono();
+            app.route('/', Scalar.serve({ document }));
+            const html = await (await app.request('/')).text();
+            expect(html).toContain('/openapi.json');
+            const json = await app.request('/openapi.json');
+            expect(await json.json()).toEqual(document);
+        });
+    });
 });

package/package.json

@@ -10,7 +10,7 @@
     "url": "git+https://github.com/scalar/scalar.git",
     "directory": "integrations/hono"
   },
-  "version": "0.11.16",
+  "version": "0.12.0",
   "engines": {
     "node": ">=22"
   },
@@ -44,7 +44,7 @@
     "documentation": "https://scalar.com/products/api-references/integrations/hono"
   },
   "dependencies": {
-    "@scalar/client-side-rendering": "0.3.9"
+    "@scalar/client-side-rendering": "0.3.10"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.10",
@@ -52,7 +52,7 @@
     "hono": "^4.12.7",
     "vite": "8.1.5",
     "vitest": "4.1.10",
-    "@scalar/openapi-to-markdown": "0.5.42"
+    "@scalar/openapi-to-markdown": "0.5.43"
   },
   "peerDependencies": {
     "hono": "^4.12.5"