@farming-labs/next 0.0.38 → 0.0.43

package/dist/api-reference.d.mts

@@ -0,0 +1,9 @@
+import { ApiReferenceConfig, DocsConfig } from "@farming-labs/docs";
+
+//#region src/api-reference.d.ts
+declare function resolveApiReferenceConfig(value: DocsConfig["apiReference"]): Required<ApiReferenceConfig>;
+declare function buildNextOpenApiDocument(config: DocsConfig): Record<string, unknown>;
+declare function withNextApiReferenceBanner(config: DocsConfig): DocsConfig;
+declare function createNextApiReference(config: DocsConfig): () => Response;
+//#endregion
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner };

package/dist/api-reference.mjs

@@ -0,0 +1,611 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { ApiReference } from "@scalar/nextjs-api-reference";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/api-reference.tsx
+const ROUTE_FILE_RE = /^route\.(ts|tsx|js|jsx)$/;
+const METHOD_RE = /export\s+(?:async\s+function|function|const)\s+(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\b/g;
+function resolveTheme(config) {
+	return config.theme;
+}
+function buildScalarCustomCss(config) {
+	const theme = resolveTheme(config);
+	const colors = theme?.ui?.colors;
+	const typography = theme?.ui?.typography?.font?.style;
+	const layout = theme?.ui?.layout;
+	const primary = colors?.primary ?? "#6366f1";
+	const border = colors?.border ?? "#2a2a2a";
+	const muted = colors?.muted ?? "#64748b";
+	const background = colors?.background ?? "#ffffff";
+	const card = colors?.card ?? background;
+	const foreground = colors?.foreground ?? "#1b1b1b";
+	const sidebarWidth = layout?.sidebarWidth ?? 280;
+	return `
+:root {
+  --scalar-font: ${typography?.sans ?? "\"Geist\", \"Inter\", \"Segoe UI\", sans-serif"};
+  --scalar-font-code: ${typography?.mono ?? "\"Geist Mono\", \"SFMono-Regular\", \"Menlo\", monospace"};
+  --scalar-theme-primary: ${primary};
+  --scalar-theme-border: ${border};
+  --scalar-theme-muted: ${muted};
+  --scalar-theme-background: ${background};
+  --scalar-theme-card: ${card};
+  --scalar-theme-foreground: ${foreground};
+}
+
+.dark-mode {
+  --scalar-background-1: color-mix(in srgb, #0b0c0b 98%, var(--scalar-theme-primary) 2%);
+  --scalar-background-2: color-mix(in srgb, #111311 96%, var(--scalar-theme-primary) 4%);
+  --scalar-background-3: color-mix(in srgb, #171917 95%, var(--scalar-theme-primary) 5%);
+  --scalar-color-1: rgba(255, 255, 255, 0.96);
+  --scalar-color-2: rgba(255, 255, 255, 0.72);
+  --scalar-color-3: rgba(255, 255, 255, 0.5);
+  --scalar-color-accent: var(--scalar-theme-primary);
+  --scalar-sidebar-color-active: var(--scalar-theme-primary);
+  --scalar-sidebar-item-active-background: color-mix(
+    in srgb,
+    var(--scalar-theme-primary) 7%,
+    transparent
+  );
+  --scalar-border-color: color-mix(
+    in srgb,
+    var(--scalar-theme-border) 22%,
+    rgba(255, 255, 255, 0.032)
+  );
+  --scalar-button-1: var(--scalar-theme-primary);
+  --scalar-button-1-color: #ffffff;
+  --scalar-button-1-hover: color-mix(in srgb, var(--scalar-theme-primary) 88%, white 12%);
+}
+
+.light-mode {
+  --scalar-background-1: var(--scalar-theme-background);
+  --scalar-background-2: color-mix(in srgb, var(--scalar-theme-card) 92%, white 8%);
+  --scalar-background-3: color-mix(in srgb, var(--scalar-theme-card) 84%, black 4%);
+  --scalar-color-1: var(--scalar-theme-foreground);
+  --scalar-color-2: var(--scalar-theme-muted);
+  --scalar-color-3: color-mix(in srgb, var(--scalar-theme-muted) 78%, white 22%);
+  --scalar-color-accent: var(--scalar-theme-primary);
+  --scalar-sidebar-color-active: var(--scalar-theme-primary);
+  --scalar-sidebar-item-active-background: color-mix(
+    in srgb,
+    var(--scalar-theme-primary) 5%,
+    transparent
+  );
+  --scalar-border-color: color-mix(in srgb, var(--scalar-theme-border) 42%, white 58%);
+  --scalar-button-1: var(--scalar-theme-primary);
+  --scalar-button-1-color: #ffffff;
+  --scalar-button-1-hover: color-mix(in srgb, var(--scalar-theme-primary) 88%, black 12%);
+}
+
+body {
+  background: var(--scalar-background-1);
+}
+
+.t-doc__sidebar {
+  width: min(${sidebarWidth}px, 100vw);
+  border-right: 1px solid var(--scalar-border-color);
+}
+
+.scalar-card,
+.t-doc__sidebar,
+.references-layout .reference-layout__content .request-card,
+.references-layout .reference-layout__content .response-card,
+.references-layout .reference-layout__content .scalar-card-header,
+.references-layout .reference-layout__content .scalar-card-footer,
+.references-layout .reference-layout__content .section,
+.references-layout .reference-layout__content .section-container {
+  border-color: var(--scalar-border-color) !important;
+}
+
+.t-doc__sidebar,
+.t-doc__sidebar * {
+  font-family: var(--scalar-font);
+}
+
+.t-doc__sidebar .sidebar-search {
+  margin: 0.5rem 0 1rem;
+}
+
+.t-doc__sidebar .sidebar-search input {
+  border-radius: 14px;
+}
+
+.t-doc__sidebar .sidebar-item,
+.t-doc__sidebar .sidebar-heading {
+  border-radius: 14px;
+}
+
+.t-doc__sidebar .sidebar-group-label {
+  font-size: 0.72rem;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--scalar-color-3);
+}
+
+.t-doc__sidebar .sidebar-item--active {
+  font-weight: 600;
+}
+
+.scalar-card,
+.references-layout .reference-layout__content .request-card,
+.references-layout .reference-layout__content .response-card {
+  border-radius: 18px;
+}
+
+.references-layout .reference-layout__content {
+  padding-top: 1.5rem;
+}
+
+.references-layout .section-content,
+.references-layout .section-flare {
+  background: transparent;
+}
+
+.references-layout .reference-layout__content,
+.references-layout .reference-layout__content * {
+  font-family: var(--scalar-font);
+}
+
+.references-layout code,
+.references-layout pre,
+.references-layout .scalar-codeblock {
+  font-family: var(--scalar-font-code);
+}
+`;
+}
+function getNextAppDir(root) {
+	if (existsSync(join(root, "src", "app"))) return "src/app";
+	return "app";
+}
+function resolveApiReferenceConfig(value) {
+	if (value === true) return {
+		enabled: true,
+		path: "api-reference",
+		routeRoot: "api",
+		exclude: []
+	};
+	if (!value) return {
+		enabled: false,
+		path: "api-reference",
+		routeRoot: "api",
+		exclude: []
+	};
+	return {
+		enabled: value.enabled !== false,
+		path: normalizePathSegment(value.path ?? "api-reference"),
+		routeRoot: normalizeRouteRoot(value.routeRoot ?? "api"),
+		exclude: normalizeApiReferenceExcludes(value.exclude)
+	};
+}
+function normalizePathSegment(value) {
+	return value.replace(/^\/+|\/+$/g, "") || "api-reference";
+}
+function normalizeRouteRoot(value) {
+	return value.replace(/^\/+|\/+$/g, "") || "api";
+}
+function normalizeExcludeMatcher(value) {
+	return value.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").replace(/\.(ts|tsx|js|jsx)$/i, "").replace(/\/route$/i, "");
+}
+function normalizeApiReferenceExcludes(values) {
+	return (values ?? []).map(normalizeExcludeMatcher).filter(Boolean);
+}
+function getRoutePathBase(config) {
+	const routeRoot = normalizeRouteRoot(config.routeRoot);
+	if (routeRoot === "app" || routeRoot === "src/app") return "";
+	if (routeRoot.startsWith("app/")) return `/${routeRoot.slice(4)}`;
+	if (routeRoot.startsWith("src/app/")) return `/${routeRoot.slice(8)}`;
+	return `/${routeRoot}`;
+}
+function resolveNextApiRouteRoot(root, config) {
+	const routeRoot = normalizeRouteRoot(config.routeRoot);
+	if (routeRoot === "app" || routeRoot.startsWith("app/") || routeRoot === "src/app" || routeRoot.startsWith("src/app/")) return join(root, ...routeRoot.split("/"));
+	return join(root, getNextAppDir(root), ...routeRoot.split("/"));
+}
+function shouldExcludeRoute(excludes, routePath, relativeFile, relativeDir) {
+	if (excludes.length === 0) return false;
+	const normalizedRoutePath = normalizeExcludeMatcher(routePath);
+	const candidates = new Set([
+		normalizedRoutePath,
+		normalizeExcludeMatcher(routePath.replace(/^\/+/, "")),
+		normalizeExcludeMatcher(relativeFile),
+		normalizeExcludeMatcher(relativeDir)
+	]);
+	return excludes.some((entry) => candidates.has(entry));
+}
+function humanizeSegment(value) {
+	return value.replace(/^\[\[?\.{3}/, "").replace(/^\[/, "").replace(/\]\]?$/, "").replace(/^\$/, "").replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function endpointSegmentFromFsSegment(value) {
+	if (value.startsWith("[[...") && value.endsWith("]]")) return `{${value.slice(5, -2)}}`;
+	if (value.startsWith("[...") && value.endsWith("]")) return `{${value.slice(4, -1)}}`;
+	if (value.startsWith("[") && value.endsWith("]")) return `{${value.slice(1, -1)}}`;
+	return value;
+}
+function getPathParamName(value) {
+	if (value.startsWith("[[...") && value.endsWith("]]")) return value.slice(5, -2);
+	if (value.startsWith("[...") && value.endsWith("]")) return value.slice(4, -1);
+	if (value.startsWith("[") && value.endsWith("]")) return value.slice(1, -1);
+}
+function extractDocBlock(source) {
+	const match = source.match(/\/\*\*([\s\S]*?)\*\//);
+	if (!match) return {};
+	const lines = match[1].split("\n").map((line) => line.replace(/^\s*\*\s?/, "").trim()).filter(Boolean).filter((line) => !line.startsWith("@"));
+	if (lines.length === 0) return {};
+	return {
+		summary: lines[0],
+		description: lines.slice(1).join(" ")
+	};
+}
+function extractMethods(source) {
+	const methods = /* @__PURE__ */ new Set();
+	for (const match of source.matchAll(METHOD_RE)) methods.add(match[1]);
+	return Array.from(methods);
+}
+function scanRouteFiles(dir) {
+	if (!existsSync(dir)) return [];
+	const results = [];
+	for (const name of readdirSync(dir)) {
+		const full = join(dir, name);
+		if (statSync(full).isDirectory()) {
+			results.push(...scanRouteFiles(full));
+			continue;
+		}
+		if (ROUTE_FILE_RE.test(name)) results.push(full);
+	}
+	return results;
+}
+function getDocsUrl(config) {
+	if (typeof config.nav?.url === "string") return config.nav.url;
+	return `/${config.entry ?? "docs"}`;
+}
+function applyTitleTemplate(config, title) {
+	const template = config.metadata?.titleTemplate;
+	if (!template) return title;
+	return template.replace("%s", title);
+}
+function getForcedMode(config) {
+	const toggle = config.themeToggle;
+	if (!toggle || typeof toggle !== "object") return void 0;
+	if (toggle.default === "dark") return "dark";
+	if (toggle.default === "light") return "light";
+}
+function isThemeToggleHidden(config) {
+	if (config.themeToggle === false) return true;
+	if (config.themeToggle && typeof config.themeToggle === "object") return config.themeToggle.enabled === false;
+	return false;
+}
+function buildPathParameters(fsSegments) {
+	const parameters = [];
+	for (const segment of fsSegments) {
+		const name = getPathParamName(segment);
+		if (!name) continue;
+		const optional = segment.startsWith("[[...");
+		parameters.push({
+			name,
+			in: "path",
+			required: !optional,
+			description: optional ? `${humanizeSegment(name)} catch-all parameter.` : `${humanizeSegment(name)} path parameter.`,
+			schema: { type: "string" }
+		});
+	}
+	return parameters;
+}
+function buildApiReferenceRoutes(config) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.enabled) return [];
+	const root = process.cwd();
+	const apiDir = resolveNextApiRouteRoot(root, apiReference);
+	const routePathBase = getRoutePathBase(apiReference);
+	const files = scanRouteFiles(apiDir);
+	const excludes = apiReference.exclude;
+	const routes = [];
+	for (const file of files) {
+		const source = readFileSync(file, "utf-8");
+		const methods = extractMethods(source);
+		if (methods.length === 0) continue;
+		const relativeFile = relative(apiDir, file).replace(/\\/g, "/");
+		const fsSegments = relativeFile.split("/").slice(0, -1).filter(Boolean);
+		const relativeDir = fsSegments.join("/");
+		const routeSegments = fsSegments.map(endpointSegmentFromFsSegment);
+		const routePath = `${routePathBase}${routeSegments.length > 0 ? `/${routeSegments.join("/")}` : ""}` || "/";
+		if (shouldExcludeRoute(excludes, routePath, relativeFile, relativeDir)) continue;
+		const docBlock = extractDocBlock(source);
+		const title = fsSegments.length > 0 ? humanizeSegment(fsSegments[fsSegments.length - 1]) : "Overview";
+		routes.push({
+			title,
+			summary: docBlock.summary ?? `${title} endpoint`,
+			description: docBlock.description,
+			routePath,
+			sourceFile: relative(root, file).replace(/\\/g, "/"),
+			methods,
+			segments: fsSegments,
+			tag: fsSegments.length > 0 ? humanizeSegment(fsSegments[0]) : "General",
+			parameters: buildPathParameters(fsSegments)
+		});
+	}
+	return routes.sort((a, b) => a.routePath.localeCompare(b.routePath));
+}
+function createOperationId(route, method) {
+	return `${method.toLowerCase()}_${route.routePath.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "")}`;
+}
+function buildRequestBody(method) {
+	if (![
+		"POST",
+		"PUT",
+		"PATCH"
+	].includes(method)) return void 0;
+	return {
+		required: method === "POST",
+		content: { "application/json": {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			example: { example: true }
+		} }
+	};
+}
+function buildResponses(method) {
+	return { "200": {
+		description: method === "DELETE" ? "Resource removed successfully." : "Request completed successfully.",
+		content: { "application/json": {
+			schema: {
+				type: "object",
+				additionalProperties: true
+			},
+			example: { ok: true }
+		} }
+	} };
+}
+function buildOpenApiPaths(routes) {
+	const paths = {};
+	for (const route of routes) {
+		const pathItem = {};
+		for (const method of route.methods) pathItem[method.toLowerCase()] = {
+			tags: [route.tag],
+			summary: route.summary,
+			description: route.description ?? route.summary,
+			operationId: createOperationId(route, method),
+			...route.parameters.length > 0 ? { parameters: route.parameters } : {},
+			...buildRequestBody(method) ? { requestBody: buildRequestBody(method) } : {},
+			responses: buildResponses(method),
+			"x-farming-labs-source": route.sourceFile
+		};
+		paths[route.routePath] = pathItem;
+	}
+	return paths;
+}
+function buildNextOpenApiDocument(config) {
+	const routes = buildApiReferenceRoutes(config);
+	const tags = Array.from(new Set(routes.map((route) => route.tag))).map((name) => ({
+		name,
+		description: `${name} endpoints`
+	}));
+	return {
+		openapi: "3.1.0",
+		info: {
+			title: "API Reference",
+			description: config.metadata?.description ?? "Generated API reference from Next.js route handlers.",
+			version: "0.0.0"
+		},
+		servers: [{ url: "/" }],
+		tags,
+		paths: buildOpenApiPaths(routes)
+	};
+}
+function DropdownIcon({ current }) {
+	const label = current === "api" ? "</>" : "▣";
+	return /* @__PURE__ */ jsx("span", {
+		"aria-hidden": "true",
+		style: {
+			display: "inline-flex",
+			width: 20,
+			height: 20,
+			alignItems: "center",
+			justifyContent: "center",
+			borderRadius: 6,
+			border: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)",
+			background: "color-mix(in srgb, var(--color-fd-card, #161616) 92%, transparent)",
+			color: "var(--color-fd-primary, currentColor)",
+			boxShadow: "0 0 0 1px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 32%, transparent)",
+			fontSize: 9,
+			fontWeight: 700
+		},
+		children: label
+	});
+}
+function SwitcherOption({ href, title, description, current }) {
+	return /* @__PURE__ */ jsxs("a", {
+		href,
+		style: {
+			display: "grid",
+			gridTemplateColumns: "20px 1fr 14px",
+			gap: 12,
+			alignItems: "start",
+			padding: "11px 12px",
+			borderRadius: 12,
+			textDecoration: "none",
+			color: "inherit",
+			background: current ? "color-mix(in srgb, var(--color-fd-primary, #3a7) 10%, transparent)" : "transparent"
+		},
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				style: {
+					display: "inline-flex",
+					width: 20,
+					height: 20,
+					alignItems: "center",
+					justifyContent: "center",
+					borderRadius: 6,
+					border: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)",
+					color: current ? "var(--color-fd-primary, currentColor)" : "var(--color-fd-muted-foreground, rgba(255,255,255,0.62))",
+					background: "color-mix(in srgb, var(--color-fd-card, #161616) 92%, transparent)",
+					boxShadow: "0 0 0 1px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 32%, transparent)",
+					fontSize: 9,
+					fontWeight: 700
+				},
+				children: title === "API Reference" ? "</>" : "▣"
+			}),
+			/* @__PURE__ */ jsxs("span", {
+				style: {
+					display: "flex",
+					flexDirection: "column",
+					gap: 4
+				},
+				children: [/* @__PURE__ */ jsx("span", {
+					style: {
+						fontSize: 13,
+						fontWeight: 600,
+						lineHeight: 1.25
+					},
+					children: title
+				}), /* @__PURE__ */ jsx("span", {
+					style: {
+						fontSize: 12,
+						opacity: .62,
+						lineHeight: 1.4
+					},
+					children: description
+				})]
+			}),
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				style: {
+					fontSize: 12,
+					opacity: current ? 1 : 0,
+					color: "var(--color-fd-primary, currentColor)",
+					paddingTop: 2
+				},
+				children: "✓"
+			})
+		]
+	});
+}
+function ApiReferenceSwitcher({ docsUrl, apiUrl, current }) {
+	return /* @__PURE__ */ jsxs("details", {
+		style: {
+			position: "relative",
+			marginBottom: 16,
+			borderRadius: 14,
+			border: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)",
+			background: "color-mix(in srgb, var(--color-fd-card, #141414) 94%, transparent)",
+			boxShadow: "0 0 0 1px color-mix(in srgb, var(--color-fd-border, #2a2a2a) 32%, transparent)",
+			overflow: "hidden"
+		},
+		children: [/* @__PURE__ */ jsxs("summary", {
+			style: {
+				listStyle: "none",
+				display: "flex",
+				alignItems: "center",
+				justifyContent: "space-between",
+				gap: 10,
+				cursor: "pointer",
+				padding: "11px 13px",
+				background: "color-mix(in srgb, var(--color-fd-card, #202020) 96%, transparent)",
+				borderBottom: "1px solid color-mix(in srgb, var(--color-fd-border, #2a2a2a) 100%, transparent)"
+			},
+			children: [/* @__PURE__ */ jsxs("span", {
+				style: {
+					display: "flex",
+					alignItems: "center",
+					gap: 10
+				},
+				children: [/* @__PURE__ */ jsx(DropdownIcon, { current }), /* @__PURE__ */ jsx("span", {
+					style: {
+						fontSize: 14,
+						fontWeight: 600
+					},
+					children: current === "api" ? "API Reference" : "Documentation"
+				})]
+			}), /* @__PURE__ */ jsx("span", {
+				"aria-hidden": "true",
+				style: {
+					fontSize: 11,
+					opacity: .56,
+					transform: "translateY(1px)"
+				},
+				children: "▿"
+			})]
+		}), /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "flex",
+				flexDirection: "column",
+				gap: 2,
+				padding: 8,
+				background: "color-mix(in srgb, var(--color-fd-card, #151515) 96%, transparent)"
+			},
+			children: [/* @__PURE__ */ jsx(SwitcherOption, {
+				href: docsUrl,
+				title: "Documentation",
+				description: "Markdown pages, guides, and concepts",
+				current: current === "docs"
+			}), /* @__PURE__ */ jsx(SwitcherOption, {
+				href: apiUrl,
+				title: "API Reference",
+				description: "Scalar-powered route handler reference",
+				current: current === "api"
+			})]
+		})]
+	});
+}
+function mergeBanner(existing, next) {
+	if (!existing) return next;
+	return /* @__PURE__ */ jsxs("div", {
+		style: {
+			display: "flex",
+			flexDirection: "column",
+			gap: 12
+		},
+		children: [existing, next]
+	});
+}
+function withNextApiReferenceBanner(config) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	if (!apiReference.enabled) return config;
+	if (config.sidebar === false) return config;
+	const switcher = /* @__PURE__ */ jsx(ApiReferenceSwitcher, {
+		docsUrl: getDocsUrl(config),
+		apiUrl: `/${apiReference.path}`,
+		current: "docs"
+	});
+	if (!config.sidebar || config.sidebar === true) return {
+		...config,
+		sidebar: { banner: switcher }
+	};
+	return {
+		...config,
+		sidebar: {
+			...config.sidebar,
+			banner: mergeBanner(config.sidebar.banner, switcher)
+		}
+	};
+}
+function createNextApiReference(config) {
+	const apiReference = resolveApiReferenceConfig(config.apiReference);
+	return ApiReference({
+		pageTitle: applyTitleTemplate(config, "API Reference"),
+		title: "API Reference",
+		content: () => buildNextOpenApiDocument(config),
+		theme: "deepSpace",
+		layout: "modern",
+		darkMode: getForcedMode(config) === "dark" ? true : void 0,
+		forceDarkModeState: getForcedMode(config),
+		hideDarkModeToggle: isThemeToggleHidden(config),
+		customCss: buildScalarCustomCss(config),
+		pathRouting: { basePath: `/${apiReference.path}` },
+		showSidebar: true,
+		defaultOpenFirstTag: true,
+		tagsSorter: "alpha",
+		operationsSorter: "alpha",
+		operationTitleSource: "summary",
+		defaultHttpClient: {
+			targetKey: "shell",
+			clientKey: "curl"
+		},
+		documentDownloadType: "json"
+	});
+}
+
+//#endregion
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner };

package/dist/config.mjs

@@ -51,10 +51,11 @@ const DOCS_LAYOUT_TEMPLATE = `\
 ${GENERATED_BANNER}
 import docsConfig from "@/docs.config";
 import { createDocsLayout, createDocsMetadata } from "@farming-labs/theme";
+import { withNextApiReferenceBanner } from "@farming-labs/next/api-reference";
 
 export const metadata = createDocsMetadata(docsConfig);
 
-const DocsLayout = createDocsLayout(docsConfig);
+const DocsLayout = createDocsLayout(withNextApiReferenceBanner(docsConfig));
 
 export default function Layout({ children }: { children: React.ReactNode }) {
   return (
@@ -74,6 +75,15 @@ export const { GET, POST } = createDocsAPI({
   i18n: docsConfig.i18n,
 });
 
+export const revalidate = false;
+`;
+const API_REFERENCE_ROUTE_TEMPLATE = `\
+${GENERATED_BANNER}
+import docsConfig from "@/docs.config";
+import { createNextApiReference } from "@farming-labs/next/api-reference";
+
+export const GET = createNextApiReference(docsConfig);
+
 export const revalidate = false;
 `;
 const FILE_EXTS = [
@@ -106,6 +116,63 @@ function readOgEndpoint(root) {
 		} catch {}
 	}
 }
+function readApiReferenceConfig(root) {
+	for (const ext of FILE_EXTS) {
+		const configPath = join(root, `docs.config.${ext}`);
+		if (!existsSync(configPath)) continue;
+		try {
+			const content = readFileSync(configPath, "utf-8");
+			if (content.match(/apiReference\s*:\s*false/)) return {
+				enabled: false,
+				path: "api-reference",
+				routeRoot: "api"
+			};
+			if (content.match(/apiReference\s*:\s*true/)) return {
+				enabled: true,
+				path: "api-reference",
+				routeRoot: "api"
+			};
+			const block = extractObjectLiteral(content, "apiReference");
+			if (!block) continue;
+			const enabledMatch = block.match(/enabled\s*:\s*(true|false)/);
+			const pathMatch = block.match(/path\s*:\s*["']([^"']+)["']/);
+			const routeRootMatch = block.match(/routeRoot\s*:\s*["']([^"']+)["']/);
+			return {
+				enabled: enabledMatch ? enabledMatch[1] !== "false" : true,
+				path: pathMatch?.[1]?.replace(/^\/+|\/+$/g, "") || "api-reference",
+				routeRoot: routeRootMatch?.[1]?.replace(/^\/+|\/+$/g, "") || "api"
+			};
+		} catch {
+			return {
+				enabled: false,
+				path: "api-reference",
+				routeRoot: "api"
+			};
+		}
+	}
+	return {
+		enabled: false,
+		path: "api-reference",
+		routeRoot: "api"
+	};
+}
+function extractObjectLiteral(content, key) {
+	const keyIndex = content.search(new RegExp(`${key}\\s*:\\s*\\{`));
+	if (keyIndex === -1) return void 0;
+	const braceStart = content.indexOf("{", keyIndex);
+	if (braceStart === -1) return void 0;
+	let depth = 0;
+	for (let index = braceStart; index < content.length; index += 1) {
+		const char = content[index];
+		if (char === "{") {
+			depth += 1;
+			continue;
+		}
+		if (char !== "}") continue;
+		depth -= 1;
+		if (depth === 0) return content.slice(braceStart + 1, index);
+	}
+}
 function withDocs(nextConfig = {}) {
 	const root = process.cwd();
 	if (!hasFile(root, "mdx-components")) writeFileSync(join(root, "mdx-components.tsx"), MDX_COMPONENTS_TEMPLATE);
@@ -123,6 +190,14 @@ function withDocs(nextConfig = {}) {
 		mkdirSync(docsApiRouteDir, { recursive: true });
 		writeFileSync(join(docsApiRouteDir, "route.ts"), DOCS_API_ROUTE_TEMPLATE);
 	}
+	const apiReference = readApiReferenceConfig(root);
+	if (apiReference.enabled && !isStaticExport) {
+		const apiReferenceRouteDir = join(root, appDir, ...apiReference.path.split("/"), "[[...slug]]");
+		if (!hasFile(apiReferenceRouteDir, "route")) {
+			mkdirSync(apiReferenceRouteDir, { recursive: true });
+			writeFileSync(join(apiReferenceRouteDir, "route.ts"), API_REFERENCE_ROUTE_TEMPLATE);
+		}
+	}
 	const ogEndpoint = readOgEndpoint(root);
 	const remarkPlugins = ["remark-gfm", "remark-frontmatter"];
 	if (ogEndpoint) remarkPlugins.push(["@farming-labs/next/mdx-plugins/remark-og", { endpoint: ogEndpoint }]);

package/dist/index.d.mts

@@ -1,2 +1,3 @@
+import { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner } from "./api-reference.mjs";
 import { withDocs } from "./config.mjs";
-export { withDocs };
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withDocs, withNextApiReferenceBanner };

package/dist/index.mjs

@@ -1,3 +1,4 @@
 import { withDocs } from "./config.mjs";
+import { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withNextApiReferenceBanner } from "./api-reference.mjs";
 
-export { withDocs };
+export { buildNextOpenApiDocument, createNextApiReference, resolveApiReferenceConfig, withDocs, withNextApiReferenceBanner };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/next",
-  "version": "0.0.38",
+  "version": "0.0.43",
   "description": "Next.js adapter for @farming-labs/docs — MDX config wrapper",
   "keywords": [
     "docs",
@@ -22,6 +22,11 @@
       "import": "./dist/index.mjs",
       "default": "./dist/index.mjs"
     },
+    "./api-reference": {
+      "types": "./dist/api-reference.d.mts",
+      "import": "./dist/api-reference.mjs",
+      "default": "./dist/api-reference.mjs"
+    },
     "./config": {
       "types": "./dist/config.d.mts",
       "import": "./dist/config.mjs",
@@ -52,6 +57,7 @@
     "@mdx-js/loader": "^3.1.0",
     "@mdx-js/react": "^3.1.0",
     "@next/mdx": "^16.1.6",
+    "@scalar/nextjs-api-reference": "0.10.3",
     "fumadocs-core": "^16.6.1",
     "remark-frontmatter": "^5.0.0",
     "remark-gfm": "^4.0.1",
@@ -59,11 +65,16 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "@types/react": "^19.2.2",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@farming-labs/docs": "0.0.43",
+    "@farming-labs/theme": "0.0.43"
   },
   "peerDependencies": {
+    "@farming-labs/docs": ">=0.0.1",
+    "@farming-labs/theme": ">=0.0.1",
     "next": ">=16.0.0",
     "react": ">=19.2.0",
     "react-dom": ">=19.2.0"