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 and CSS: createNextApiReferencePage, createNextApiReferenceLayout, and @farming-labs/next/api-reference.css.
  • withDocs() now generates app/api-reference/[[...slug]]/page.tsx and app/api-reference/layout.tsx.
  • Next.js supports absolute and 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/[[...slug]]/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 3d50118. 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 30, 2026 7:44pm

[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.}