chore: Upgrade docs framework to Next 16.2.6 and Fumadocs 16.9.1 (#3944)

chore: Upgrade docs framework to latest

Author: mrousavy

bun.lock

@@ -23,14 +23,14 @@
     "@heroicons/react": "^2.2.0",
     "@r4ai/remark-callout": "^0.6.2",
     "@vercel/analytics": "^2.0.1",
-    "fumadocs-core": "16.6.17",
-    "fumadocs-docgen": "^3.0.4",
-    "fumadocs-mdx": "14.2.10",
-    "fumadocs-typescript": "5.1.5",
-    "fumadocs-ui": "16.6.17",
+    "fumadocs-core": "16.9.1",
+    "fumadocs-docgen": "3.0.10",
+    "fumadocs-mdx": "15.0.9",
+    "fumadocs-typescript": "5.2.6",
+    "fumadocs-ui": "16.9.1",
     "lucide-react": "0.575.0",
     "motion": "^12.36.0",
-    "next": "16.1.6",
+    "next": "16.2.6",
     "picocolors": "^1.1.1",
     "react": "19.2.3",
     "react-dom": "19.2.3"

docs/package.json

@@ -1,51 +1,49 @@
 import { describe, expect, test } from 'bun:test'
 import type { Folder, Item, Root } from 'fumadocs-core/page-tree'
 import {
+  type ContentStorage,
+  type ContentStorageMetaFile,
   type ContentStoragePageFile,
   FileSystem,
+  type PageData as FumadocsPageData,
   type PageTreeBuilderContext,
-  type SourceConfig,
 } from 'fumadocs-core/source'
 import { createApiReferenceTreePlugin } from '@/lib/source/api-reference-tree-plugin'
 import { createPlatformLabelPlugin } from '@/lib/source/platform-label-plugin'
 
-type PageData = {
+type TestPageData = FumadocsPageData & {
   title: string
   hybridParent?: string
   platforms?: string[]
 }
 
-type PageFile = {
+type PageFile = ContentStoragePageFile<undefined, TestPageData>
+type PageFileInput = {
   format: 'page'
-  data: PageData
-}
-
-type TestSourceConfig = SourceConfig & {
-  pageData: PageData
-}
-
-type TestLoaderConfig = {
-  source: TestSourceConfig
-  i18n: undefined
+  data: TestPageData
 }
+type TestStorage = ContentStorage<PageFile, ContentStorageMetaFile>
 
 function createPage(file: string, title: string): Item {
   return {
     $id: file,
-    $ref: { file },
+    $ref: file,
     type: 'page',
     name: title,
     url: `/api/${title}`,
   }
 }
 
 function createContext(
-  files: Record<string, PageFile>,
-): PageTreeBuilderContext<TestSourceConfig> {
-  const storage = new FileSystem<ContentStoragePageFile<TestSourceConfig>>()
+  files: Record<string, PageFileInput>,
+): PageTreeBuilderContext<TestStorage> {
+  const storage = new FileSystem<
+    PageFile | ContentStorageMetaFile
+  >() as TestStorage
 
   for (const [filePath, file] of Object.entries(files)) {
     storage.write(filePath, {
+      type: undefined,
       path: filePath,
       format: 'page',
       slugs: [file.data.title],
@@ -55,27 +53,29 @@ function createContext(
 
   const getUrl = () => ''
   // Fumadocs exposes PageTreeBuilder in its type surface, but not from the runtime module.
-  const builder = {} as PageTreeBuilderContext<TestSourceConfig>['builder']
+  const builder = {} as PageTreeBuilderContext<TestStorage>['builder']
   return {
-    idPrefix: 'test',
-    noRef: false,
     transformers: [],
     builder,
     storage,
-    getUrl,
+    options: {
+      idPrefix: 'test',
+      noRef: false,
+      url: getUrl,
+    },
   }
 }
 
 function getNodeTitle(
   node: Folder['children'][number],
-  files: Record<string, PageFile>,
+  files: Record<string, PageFileInput>,
 ): string {
-  if (node.type === 'folder' && node.index?.$ref?.file) {
-    return files[node.index.$ref.file]?.data.title ?? ''
+  if (node.type === 'folder' && node.index?.$ref) {
+    return files[node.index.$ref]?.data.title ?? ''
   }
 
-  if (node.type === 'page' && node.$ref?.file) {
-    return files[node.$ref.file]?.data.title ?? ''
+  if (node.type === 'page' && node.$ref) {
+    return files[node.$ref]?.data.title ?? ''
   }
 
   return ''
@@ -94,7 +94,7 @@ function getFolderByTitle(root: Root, title: string): Folder {
 
 function getChildFolderByTitle(
   folder: Folder,
-  files: Record<string, PageFile>,
+  files: Record<string, PageFileInput>,
   title: string,
 ): Folder {
   const child = folder.children.find(
@@ -110,7 +110,7 @@ function getChildFolderByTitle(
 
 describe('api reference tree plugin', () => {
   test('nests platform-labeled hybrid children under their stable hybrid parent', () => {
-    const files: Record<string, PageFile> = {
+    const files: Record<string, PageFileInput> = {
       'CameraOutput.mdx': {
         format: 'page',
         data: { title: 'CameraOutput' },
@@ -181,8 +181,8 @@ describe('api reference tree plugin', () => {
     }
 
     const context = createContext(files)
-    const apiTreePlugin = createApiReferenceTreePlugin<TestLoaderConfig>()
-    const platformLabelPlugin = createPlatformLabelPlugin<TestLoaderConfig>()
+    const apiTreePlugin = createApiReferenceTreePlugin<TestStorage>()
+    const platformLabelPlugin = createPlatformLabelPlugin<TestStorage>()
     const transformApiTree = apiTreePlugin.transformPageTree?.root
     const transformPlatformLabels = platformLabelPlugin.transformPageTree?.root
 

docs/src/lib/source/api-reference-tree-plugin.test.ts

@@ -5,10 +5,9 @@ import type {
   Root as PageTreeRoot,
 } from 'fumadocs-core/page-tree'
 import type {
-  LoaderConfig,
   LoaderPlugin,
+  PageData,
   PageTreeBuilderContext,
-  SourceConfig,
 } from 'fumadocs-core/source'
 import {
   API_SECTION_NAME_BY_KEY,
@@ -18,19 +17,17 @@ import {
 } from '@/lib/shared/api-reference.shared'
 import {
   getNodeNameAsString,
+  type PageDataStorage,
   type PageDataWithHybridParent,
   type PageDataWithTitle,
   readHybridParent,
   readStablePageTitle,
 } from '@/lib/source/page-tree'
 
-type ApiReferencePageData = PageDataWithTitle & PageDataWithHybridParent
-type ApiReferenceSourceConfig = SourceConfig & {
-  pageData: ApiReferencePageData
-}
-type ApiReferenceLoaderConfig = LoaderConfig & {
-  source: ApiReferenceSourceConfig
-}
+type ApiReferencePageData = PageData &
+  PageDataWithTitle &
+  PageDataWithHybridParent
+type ApiReferenceStorage = PageDataStorage<ApiReferencePageData>
 
 function withCanonicalSectionName(folder: PageTreeFolder): PageTreeFolder {
   const folderName = getNodeNameAsString(folder.name)
@@ -108,9 +105,9 @@ function reorderSectionFolders(folder: PageTreeFolder): PageTreeFolder {
 }
 
 function nestHybridObjectChildren<
-  Config extends ApiReferenceSourceConfig = ApiReferenceSourceConfig,
+  Storage extends ApiReferenceStorage = ApiReferenceStorage,
 >(
-  context: PageTreeBuilderContext<Config>,
+  context: PageTreeBuilderContext<Storage>,
   folder: PageTreeFolder,
 ): PageTreeFolder {
   const pageNodes = folder.children.filter(
@@ -189,7 +186,8 @@ function nestHybridObjectChildren<
   const createHybridNodeId = (seed: string): string => {
     hybridNodeCounter += 1
     const safeSeed = seed.toLowerCase().replace(/[^a-z0-9]+/g, '-')
-    return `${context.idPrefix}-hybrid-${safeSeed}-${hybridNodeCounter}`
+    const idPrefix = context.options.idPrefix ?? 'api-reference'
+    return `${idPrefix}-hybrid-${safeSeed}-${hybridNodeCounter}`
   }
 
   const createNode = (
@@ -270,8 +268,8 @@ function nestHybridObjectChildren<
 }
 
 function transformApiTreeNode<
-  Config extends ApiReferenceSourceConfig = ApiReferenceSourceConfig,
->(context: PageTreeBuilderContext<Config>, node: PageTreeNode): PageTreeNode {
+  Storage extends ApiReferenceStorage = ApiReferenceStorage,
+>(context: PageTreeBuilderContext<Storage>, node: PageTreeNode): PageTreeNode {
   if (node.type !== 'folder') {
     return node
   }
@@ -291,12 +289,12 @@ function transformApiTreeNode<
 }
 
 export function createApiReferenceTreePlugin<
-  Config extends ApiReferenceLoaderConfig = ApiReferenceLoaderConfig,
->(): LoaderPlugin<Config> {
+  Storage extends ApiReferenceStorage = ApiReferenceStorage,
+>(): LoaderPlugin<Storage> {
   return {
     name: 'api-reference-tree',
     transformPageTree: {
-      root(this: PageTreeBuilderContext<Config['source']>, node: PageTreeRoot) {
+      root(this: PageTreeBuilderContext<Storage>, node: PageTreeRoot) {
         return {
           ...node,
           children: node.children.map((child) =>

docs/src/lib/source/api-reference-tree-plugin.ts

@@ -2,25 +2,36 @@ import type {
   Item as PageTreeItem,
   Node as PageTreeNode,
 } from 'fumadocs-core/page-tree'
-import type { PageTreeBuilderContext, SourceConfig } from 'fumadocs-core/source'
+import type {
+  ContentStorage,
+  ContentStorageMetaFile,
+  ContentStoragePageFile,
+  PageData,
+  PageTreeBuilderContext,
+} from 'fumadocs-core/source'
 
-export type PageDataWithTitle = {
+export type PageDataWithTitle = PageData & {
   title?: string
 }
 
-export type PageDataWithHybridParent = {
+export type PageDataWithHybridParent = PageData & {
   hybridParent?: string
 }
 
+export type PageDataStorage<Data extends PageData = PageData> = ContentStorage<
+  ContentStoragePageFile<string | undefined, Data>,
+  ContentStorageMetaFile
+>
+
 export function getNodeNameAsString(name: PageTreeNode['name']): string {
   return typeof name === 'string' ? name : ''
 }
 
-export function readPageData<Config extends SourceConfig>(
-  context: PageTreeBuilderContext<Config>,
+export function readPageData<Storage extends PageDataStorage>(
+  context: PageTreeBuilderContext<Storage>,
   item: PageTreeItem,
-): Config['pageData'] | null {
-  const filePath = item.$ref?.file
+): Storage['$inferPage']['data'] | null {
+  const filePath = item.$ref
   if (typeof filePath !== 'string' || filePath.length === 0) {
     return null
   }
@@ -34,24 +45,24 @@ export function readPageData<Config extends SourceConfig>(
 }
 
 export function readPageTitle<
-  Config extends SourceConfig & { pageData: PageDataWithTitle },
->(context: PageTreeBuilderContext<Config>, item: PageTreeItem): string | null {
+  Storage extends PageDataStorage<PageDataWithTitle>,
+>(context: PageTreeBuilderContext<Storage>, item: PageTreeItem): string | null {
   const title = readPageData(context, item)?.title
   return typeof title === 'string' && title.length > 0 ? title : null
 }
 
 export function readHybridParent<
-  Config extends SourceConfig & { pageData: PageDataWithHybridParent },
->(context: PageTreeBuilderContext<Config>, item: PageTreeItem): string | null {
+  Storage extends PageDataStorage<PageDataWithHybridParent>,
+>(context: PageTreeBuilderContext<Storage>, item: PageTreeItem): string | null {
   const hybridParent = readPageData(context, item)?.hybridParent
   return typeof hybridParent === 'string' && hybridParent.length > 0
     ? hybridParent
     : null
 }
 
 export function readStablePageTitle<
-  Config extends SourceConfig & { pageData: PageDataWithTitle },
->(context: PageTreeBuilderContext<Config>, item: PageTreeItem): string | null {
+  Storage extends PageDataStorage<PageDataWithTitle>,
+>(context: PageTreeBuilderContext<Storage>, item: PageTreeItem): string | null {
   const title = readPageTitle(context, item)
   if (title != null) {
     return title

docs/src/lib/source/page-tree.ts

@@ -4,24 +4,19 @@ import type {
   Root as PageTreeRoot,
 } from 'fumadocs-core/page-tree'
 import type {
-  LoaderConfig,
   LoaderPlugin,
+  PageData,
   PageTreeBuilderContext,
-  SourceConfig,
 } from 'fumadocs-core/source'
 import { createElement } from 'react'
 import {
   type PageDataWithPlatforms,
   readSinglePlatformFromPageData,
 } from '@/lib/platforms'
-import { readPageData } from '@/lib/source/page-tree'
+import { type PageDataStorage, readPageData } from '@/lib/source/page-tree'
 
-type PlatformSourceConfig = SourceConfig & {
-  pageData: PageDataWithPlatforms
-}
-type PlatformLoaderConfig = LoaderConfig & {
-  source: PlatformSourceConfig
-}
+type PlatformPageData = PageData & PageDataWithPlatforms
+type PlatformStorage = PageDataStorage<PlatformPageData>
 
 const SIDEBAR_ITEM_CONTENT_CLASS = 'api-sidebar-item-content'
 const SIDEBAR_ITEM_LABEL_CLASS = 'api-sidebar-item-label'
@@ -40,8 +35,8 @@ function withSidebarPlatformLabel(
 }
 
 function withPlatformLabelOnItem<
-  Config extends PlatformSourceConfig = PlatformSourceConfig,
->(context: PageTreeBuilderContext<Config>, item: PageTreeItem): PageTreeItem {
+  Storage extends PlatformStorage = PlatformStorage,
+>(context: PageTreeBuilderContext<Storage>, item: PageTreeItem): PageTreeItem {
   const platform = readSinglePlatformFromPageData(readPageData(context, item))
   if (platform == null) {
     return item
@@ -53,9 +48,10 @@ function withPlatformLabelOnItem<
   }
 }
 
-function withPlatformLabels<
-  Config extends PlatformSourceConfig = PlatformSourceConfig,
->(context: PageTreeBuilderContext<Config>, node: PageTreeNode): PageTreeNode {
+function withPlatformLabels<Storage extends PlatformStorage = PlatformStorage>(
+  context: PageTreeBuilderContext<Storage>,
+  node: PageTreeNode,
+): PageTreeNode {
   if (node.type === 'page') {
     return withPlatformLabelOnItem(context, node)
   }
@@ -76,12 +72,12 @@ function withPlatformLabels<
 }
 
 export function createPlatformLabelPlugin<
-  Config extends PlatformLoaderConfig = PlatformLoaderConfig,
->(): LoaderPlugin<Config> {
+  Storage extends PlatformStorage = PlatformStorage,
+>(): LoaderPlugin<Storage> {
   return {
     name: 'page-tree-platform-labels',
     transformPageTree: {
-      root(this: PageTreeBuilderContext<Config['source']>, node: PageTreeRoot) {
+      root(this: PageTreeBuilderContext<Storage>, node: PageTreeRoot) {
         return {
           ...node,
           children: node.children.map((child) =>

docs/src/lib/source/platform-label-plugin.ts

@@ -9,6 +9,9 @@
     "skipLibCheck": true,
     "esModuleInterop": true,
     "allowSyntheticDefaultImports": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    },
     "types": ["node"]
   },
   "include": [