@scalar/nextjs-api-reference 0.11.18 → 0.12.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalar/nextjs-api-reference
 
+## 0.12.1
+
+## 0.12.0
+
+### Minor Changes
+
+- [#10100](https://github.com/scalar/scalar/pull/10100): Support request-specific async configuration and custom response headers. Export configuration and handler option types.
+
+### Patch Changes
+
+- [#10105](https://github.com/scalar/scalar/pull/10105): Add production browser compatibility coverage for Next.js 15 and 16.
+
 ## 0.11.18
 
 ## 0.11.17

package/README.md

@@ -1,7 +1,7 @@
 <!--
   This file is auto-generated by the Scalar README generator.
   Command: pnpm --filter @scalar-internal/build-scripts start generate-readme
-  
+
   Do not edit this file manually. Changes will be lost when the file is regenerated.
 -->
 
@@ -31,6 +31,23 @@ Scalar is an open-source API platform for teams who want beautiful developer int
 
 [Read the documentation here](https://scalar.com/products/api-references/integrations/nextjs)
 
+### Quickstart
+
+```bash
+npm install @scalar/nextjs-api-reference
+```
+
+Put your OpenAPI description in `public/openapi.json` and create:
+
+```typescript
+// app/scalar/route.ts
+import { ApiReference } from '@scalar/nextjs-api-reference'
+
+export const GET = ApiReference({ url: '/openapi.json' })
+```
+
+Open `/scalar`. To embed Scalar in your application layout, follow the [App Router page guide](https://scalar.com/products/api-references/integrations/nextjs).
+
 ## Changelog
 
 See [CHANGELOG.md](https://github.com/scalar/scalar/blob/main/integrations/nextjs/CHANGELOG.md) for a list of changes.

package/dist/index.cjs

@@ -128,36 +128,25 @@ var customTheme = `
 `;
 //#endregion
 //#region src/ApiReference.ts
-/**
-* The default configuration for the API Reference.
-*/
-var DEFAULT_CONFIGURATION = { _integration: "nextjs" };
-/**
-* Next.js adapter for an Api Reference
-*
-* {@link https://github.com/scalar/scalar/tree/main/documentation/configuration.md Configuration}
-*
-* @params config - the Api Reference config object
-* @params options - reserved for future use to add customization to the response
-*/
-var ApiReference = (givenConfiguration) => {
-	const configuration = {
-		...DEFAULT_CONFIGURATION,
-		...givenConfiguration
-	};
-	return () => {
-		const { cdn, pageTitle, nonce, ...config } = configuration;
-		const referenceDocument = (0, _scalar_client_side_rendering.renderApiReference)({
-			config,
-			pageTitle,
-			cdn,
-			nonce
-		}, customTheme);
-		return new Response(referenceDocument, {
-			status: 200,
-			headers: { "Content-Type": "text/html" }
-		});
+/** Render a fresh response so headers and request-specific configuration are never shared. */
+var renderResponse = (configuration, options) => {
+	const { cdn, pageTitle, nonce, ...config } = {
+		_integration: "nextjs",
+		...configuration
 	};
+	const headers = new Headers(options.headers);
+	headers.set("Content-Type", "text/html; charset=utf-8");
+	return new Response((0, _scalar_client_side_rendering.renderApiReference)({
+		config,
+		pageTitle,
+		cdn,
+		nonce
+	}, customTheme), { headers });
 };
+function ApiReference(configuration, options = {}) {
+	if (typeof configuration === "function") return async (request) => renderResponse(await configuration(request), options);
+	const staticConfiguration = { ...configuration };
+	return () => renderResponse(staticConfiguration, options);
+}
 //#endregion
 exports.ApiReference = ApiReference;

package/dist/index.d.ts

@@ -1,18 +1,21 @@
 import { HtmlRenderingConfiguration } from '@scalar/client-side-rendering';
 
-/**
- * Next.js adapter for an Api Reference
- *
- * {@link https://github.com/scalar/scalar/tree/main/documentation/configuration.md Configuration}
- *
- * @params config - the Api Reference config object
- * @params options - reserved for future use to add customization to the response
- */
-export declare const ApiReference: (givenConfiguration: Partial<ApiReferenceConfiguration>) => (() => Response);
+/** Serve a standalone reference using static configuration. */
+export declare function ApiReference(configuration: Partial<ApiReferenceConfiguration>, options?: ApiReferenceOptions): () => Response;
 
-/**
- * The configuration for the Scalar API Reference for Next.js
- */
-declare type ApiReferenceConfiguration = HtmlRenderingConfiguration;
+/** Resolve configuration for each request. Rejections propagate to Next.js error handling. */
+export declare function ApiReference(configuration: ApiReferenceConfigurationFactory, options?: ApiReferenceOptions): (request: Request) => Promise<Response>;
+
+/** Configuration serialized into the browser's API reference. Do not include server secrets. */
+export declare type ApiReferenceConfiguration = HtmlRenderingConfiguration;
+
+/** Resolve browser configuration separately for every incoming request. */
+export declare type ApiReferenceConfigurationFactory = (request: Request) => Partial<ApiReferenceConfiguration> | Promise<Partial<ApiReferenceConfiguration>>;
+
+/** HTTP response options. The HTML content type is always set by the handler. */
+export declare type ApiReferenceOptions = {
+    /** Additional response headers, such as Cache-Control or Content-Security-Policy. */
+    headers?: HeadersInit;
+};
 
 export { }

package/dist/index.js

@@ -127,36 +127,25 @@ var customTheme = `
 `;
 //#endregion
 //#region src/ApiReference.ts
-/**
-* The default configuration for the API Reference.
-*/
-var DEFAULT_CONFIGURATION = { _integration: "nextjs" };
-/**
-* Next.js adapter for an Api Reference
-*
-* {@link https://github.com/scalar/scalar/tree/main/documentation/configuration.md Configuration}
-*
-* @params config - the Api Reference config object
-* @params options - reserved for future use to add customization to the response
-*/
-var ApiReference = (givenConfiguration) => {
-	const configuration = {
-		...DEFAULT_CONFIGURATION,
-		...givenConfiguration
-	};
-	return () => {
-		const { cdn, pageTitle, nonce, ...config } = configuration;
-		const referenceDocument = renderApiReference({
-			config,
-			pageTitle,
-			cdn,
-			nonce
-		}, customTheme);
-		return new Response(referenceDocument, {
-			status: 200,
-			headers: { "Content-Type": "text/html" }
-		});
+/** Render a fresh response so headers and request-specific configuration are never shared. */
+var renderResponse = (configuration, options) => {
+	const { cdn, pageTitle, nonce, ...config } = {
+		_integration: "nextjs",
+		...configuration
 	};
+	const headers = new Headers(options.headers);
+	headers.set("Content-Type", "text/html; charset=utf-8");
+	return new Response(renderApiReference({
+		config,
+		pageTitle,
+		cdn,
+		nonce
+	}, customTheme), { headers });
 };
+function ApiReference(configuration, options = {}) {
+	if (typeof configuration === "function") return async (request) => renderResponse(await configuration(request), options);
+	const staticConfiguration = { ...configuration };
+	return () => renderResponse(staticConfiguration, options);
+}
 //#endregion
 export { ApiReference };

package/dist/index.umd.cjs

@@ -130,37 +130,26 @@
 `;
 	//#endregion
 	//#region src/ApiReference.ts
-	/**
-	* The default configuration for the API Reference.
-	*/
-	var DEFAULT_CONFIGURATION = { _integration: "nextjs" };
-	/**
-	* Next.js adapter for an Api Reference
-	*
-	* {@link https://github.com/scalar/scalar/tree/main/documentation/configuration.md Configuration}
-	*
-	* @params config - the Api Reference config object
-	* @params options - reserved for future use to add customization to the response
-	*/
-	var ApiReference = (givenConfiguration) => {
-		const configuration = {
-			...DEFAULT_CONFIGURATION,
-			...givenConfiguration
-		};
-		return () => {
-			const { cdn, pageTitle, nonce, ...config } = configuration;
-			const referenceDocument = (0, _scalar_client_side_rendering.renderApiReference)({
-				config,
-				pageTitle,
-				cdn,
-				nonce
-			}, customTheme);
-			return new Response(referenceDocument, {
-				status: 200,
-				headers: { "Content-Type": "text/html" }
-			});
+	/** Render a fresh response so headers and request-specific configuration are never shared. */
+	var renderResponse = (configuration, options) => {
+		const { cdn, pageTitle, nonce, ...config } = {
+			_integration: "nextjs",
+			...configuration
 		};
+		const headers = new Headers(options.headers);
+		headers.set("Content-Type", "text/html; charset=utf-8");
+		return new Response((0, _scalar_client_side_rendering.renderApiReference)({
+			config,
+			pageTitle,
+			cdn,
+			nonce
+		}, customTheme), { headers });
 	};
+	function ApiReference(configuration, options = {}) {
+		if (typeof configuration === "function") return async (request) => renderResponse(await configuration(request), options);
+		const staticConfiguration = { ...configuration };
+		return () => renderResponse(staticConfiguration, options);
+	}
 	//#endregion
 	exports.ApiReference = ApiReference;
 });

package/package.json

@@ -18,7 +18,7 @@
     "openapi",
     "swagger"
   ],
-  "version": "0.11.18",
+  "version": "0.12.1",
   "engines": {
     "node": ">=22"
   },
@@ -47,10 +47,14 @@
         "type": "npm-license"
       }
     ],
-    "documentation": "https://scalar.com/products/api-references/integrations/nextjs"
+    "documentation": "https://scalar.com/products/api-references/integrations/nextjs",
+    "extraContent": {
+      "headline": "Quickstart",
+      "content": "```bash\nnpm install @scalar/nextjs-api-reference\n```\n\nPut your OpenAPI description in `public/openapi.json` and create:\n\n```typescript\n// app/scalar/route.ts\nimport { ApiReference } from '@scalar/nextjs-api-reference'\n\nexport const GET = ApiReference({ url: '/openapi.json' })\n```\n\nOpen `/scalar`. To embed Scalar in your application layout, follow the [App Router page guide](https://scalar.com/products/api-references/integrations/nextjs)."
+    }
   },
   "dependencies": {
-    "@scalar/client-side-rendering": "0.4.0"
+    "@scalar/client-side-rendering": "0.4.2"
   },
   "devDependencies": {
     "@types/node": "^24.1.0",