feat: api reference spec for fumadocs

[Kinfe123]

Summary by cubic

Adds a Fumadocs-based API reference renderer and a Next.js integration that auto-generates the page and layout. Supports hosted and same-origin OpenAPI specs, and ships a public CSS file for the Fumadocs UI.

• New Features

  • New apiReference.renderer: "fumadocs" or "scalar".
  • Framework-aware defaults: Next.js defaults to "fumadocs"; TanStack Start, SvelteKit, Astro, and Nuxt default to "scalar".
  • Next.js helpers: createNextApiReferencePage, createNextApiReferenceLayout, and @farming-labs/next/api-reference.css.
  • withDocs() now generates app/api-reference/page.tsx and app/api-reference/layout.tsx.
  • Next.js supports request-relative specUrl (e.g. /api/openapi-spec), with an example route and docs.
  • Exposes resolveApiReferenceRenderer and ApiReferenceRenderer in @farming-labs/docs; adds getNextApiReferenceMode and getNextApiReferenceSourceState in @farming-labs/next.

• Migration

  • To keep Scalar in Next.js, set renderer: "scalar" in docs.config.tsx.
  • If migrating to Fumadocs, replace the old app/api-reference/[[...slug]]/route.ts with the generated app/api-reference/page.tsx and layout.tsx. If creating pages manually, import @farming-labs/next/api-reference.css.
  • If you pass specUrl on Next.js, you can now use same-origin paths like /api/openapi-spec.

^{Written for commit e59a039. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Error		Mar 27, 2026 11:06pm

[cubic-dev-ai]

3 issues found across 30 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/next/src/config.ts">

<violation number="1" location="packages/next/src/config.ts:140">
P2: `resolvePackageSubpath` only treats paths starting with `/` as absolute. On Windows this will strip `dist/index.js` from real absolute paths and point the alias at a non-existent location. Use a cross-platform absolute-path check (e.g., drive-letter regex or `path.isAbsolute`).</violation>
</file>

<file name="packages/next/vitest.config.ts">

<violation number="1" location="packages/next/vitest.config.ts:7">
P2: `__dirname` is undefined in this package’s ESM context, so the Vitest config will throw when resolving these aliases. Use `import.meta.url`-based paths instead.</violation>
</file>

<file name="packages/docs/src/cli/init.ts">

<violation number="1" location="packages/docs/src/cli/init.ts:1254">
P2: Use a catch-all route for the API reference page so deep links (e.g., `/api-reference/...`) resolve correctly. The current scaffold writes only `/api-reference/page.tsx`, which won’t match subpaths.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: resolvePackageSubpath only treats paths starting with / as absolute. On Windows this will strip dist/index.js from real absolute paths and point the alias at a non-existent location. Use a cross-platform absolute-path check (e.g., drive-letter regex or path.isAbsolute).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/next/src/config.ts, line 140:

<comment>`resolvePackageSubpath` only treats paths starting with `/` as absolute. On Windows this will strip `dist/index.js` from real absolute paths and point the alias at a non-existent location. Use a cross-platform absolute-path check (e.g., drive-letter regex or `path.isAbsolute`).</comment>

<file context>
@@ -96,10 +97,92 @@ export const GET = createNextApiReference(docsConfig);
+}
+
+function resolvePackageSubpath(packageDir: string, relativePath: string): string {
+  if (!packageDir.startsWith("/")) return `${packageDir}/${relativePath.replace(/^dist\//, "").replace(/\/index\.js$/, "")}`;
+  return join(packageDir, relativePath);
+}
</file context>

Suggested change

	if (!packageDir.startsWith("/")) return `${packageDir}/${relativePath.replace(/^dist\//, "").replace(/\/index\.js$/, "")}`;
	const isAbsolutePath = packageDir.startsWith("/") || /^[A-Za-z]:[\\/]/.test(packageDir);
	if (!isAbsolutePath) return `${packageDir}/${relativePath.replace(/^dist\//, "").replace(/\/index\.js$/, "")}`;

[cubic-dev-ai]

P2: __dirname is undefined in this package’s ESM context, so the Vitest config will throw when resolving these aliases. Use import.meta.url-based paths instead.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/next/vitest.config.ts, line 7:

<comment>`__dirname` is undefined in this package’s ESM context, so the Vitest config will throw when resolving these aliases. Use `import.meta.url`-based paths instead.</comment>

<file context>
@@ -1,6 +1,13 @@
 export default defineConfig({
+  resolve: {
+    alias: {
+      "@farming-labs/docs/server": resolve(__dirname, "../docs/src/server.ts"),
+      "@farming-labs/docs": resolve(__dirname, "../docs/src/index.ts"),
+    },
</file context>

[cubic-dev-ai]

P2: Use a catch-all route for the API reference page so deep links (e.g., /api-reference/...) resolve correctly. The current scaffold writes only /api-reference/page.tsx, which won’t match subpaths.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/docs/src/cli/init.ts, line 1254:

<comment>Use a catch-all route for the API reference page so deep links (e.g., `/api-reference/...`) resolve correctly. The current scaffold writes only `/api-reference/page.tsx`, which won’t match subpaths.</comment>

<file context>
@@ -1251,8 +1251,8 @@ function scaffoldNextJs(
   if (cfg.apiReference) {
-    const apiReferenceRoute = `${appDir}/${cfg.apiReference.path}/[[...slug]]/route.ts`;
-    write(apiReferenceRoute, nextApiReferenceRouteTemplate(cfg, apiReferenceRoute));
+    const apiReferencePage = `${appDir}/${cfg.apiReference.path}/page.tsx`;
+    write(apiReferencePage, nextApiReferencePageTemplate(cfg, apiReferencePage));
   }
</file context>

Suggested change

	const apiReferencePage = `${appDir}/${cfg.apiReference.path}/page.tsx`;
	const apiReferencePage = `${appDir}/${cfg.apiReference.path}/[[...slug]]/page.tsx`;