docs: improve references loading (#13761)

* docs: improve references loading

* remove comment

* try remove generate metadata

* improvements and fixes

www/apps/resources/.env.sample

@@ -1,5 +1,5 @@
 # ESSENTIAL FOR DEV
-NEXT_PUBLIC_ENV=development
+NEXT_PUBLIC_ENV=development # use production when creating a build
 NEXT_PUBLIC_BASE_URL=http://localhost:3000
 NEXT_PUBLIC_BASE_PATH=/resources
 

www/apps/resources/app/api/references/[...slug]/route.ts

@@ -0,0 +1,119 @@
+import { unstable_cache } from "next/cache"
+import path from "path"
+import fs from "fs/promises"
+import mdxOptions from "@/mdx-options.mjs"
+import {
+  typeListLinkFixerPlugin,
+  localLinksRehypePlugin,
+  workflowDiagramLinkFixerPlugin,
+  prerequisitesLinkFixerPlugin,
+  recmaInjectMdxDataPlugin,
+} from "remark-rehype-plugins"
+import { serialize } from "next-mdx-remote-client/serialize"
+
+type GetRouteProps = {
+  params: Promise<{
+    slug: string[]
+  }>
+}
+
+export async function GET(request: Request, { params }: GetRouteProps) {
+  const { slug } = await params
+  const fileData = await loadReferencesFile(slug)
+
+  if (!fileData) {
+    return new Response(
+      JSON.stringify({
+        error: {
+          name: "NotFound",
+          message: "Reference file not found",
+        },
+      }),
+      {
+        status: 404,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      }
+    )
+  }
+
+  return new Response(JSON.stringify(fileData.serialized), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json",
+    },
+  })
+}
+
+const loadReferencesFile = unstable_cache(async (slug: string[]) => {
+  path.join(process.cwd(), "references")
+  const monoRepoPath = path.resolve("..", "..", "..")
+
+  const pathname = `/references/${slug.join("/")}`
+  const slugChanges = (await import("@/generated/slug-changes.mjs")).slugChanges
+  const filesMap = (await import("@/generated/files-map.mjs")).filesMap
+  const fileDetails =
+    slugChanges.find((f) => f.newSlug === pathname) ||
+    filesMap.find((f) => f.pathname === pathname)
+  if (!fileDetails) {
+    return undefined
+  }
+  const fullPath = path.join(monoRepoPath, fileDetails.filePath)
+
+  const fileContent = await fs.readFile(fullPath, "utf-8")
+
+  const pluginOptions = {
+    filePath: fullPath,
+    basePath: process.cwd(),
+  }
+  const serialized = await serialize({
+    source: fileContent,
+    options: {
+      disableImports: true,
+      mdxOptions: {
+        development: process.env.NEXT_PUBLIC_ENV === "development",
+        format: "mdx",
+        rehypePlugins: [
+          ...mdxOptions.options.rehypePlugins,
+          [
+            typeListLinkFixerPlugin,
+            {
+              ...pluginOptions,
+              checkLinksType: "md",
+            },
+          ],
+          [
+            workflowDiagramLinkFixerPlugin,
+            {
+              ...pluginOptions,
+              checkLinksType: "value",
+            },
+          ],
+          [
+            prerequisitesLinkFixerPlugin,
+            {
+              ...pluginOptions,
+              checkLinksType: "value",
+            },
+          ],
+          [localLinksRehypePlugin, pluginOptions],
+        ],
+        remarkPlugins: [...mdxOptions.options.remarkPlugins],
+        recmaPlugins: [
+          [
+            recmaInjectMdxDataPlugin,
+            { isRemoteMdx: true, mode: process.env.NODE_ENV },
+          ],
+        ],
+      },
+    },
+  })
+  return {
+    serialized,
+    content: fileContent,
+    path: fullPath,
+  }
+})
+
+export const dynamic = "force-static"

www/apps/resources/app/references/[...slug]/page.tsx

@@ -1,21 +1,10 @@
-import { MDXRemote, MDXRemoteSerializeResult } from "next-mdx-remote/rsc"
-import { serialize } from "next-mdx-remote/serialize"
-import path from "path"
-import { promises as fs } from "fs"
-import { notFound } from "next/navigation"
-import {
-  typeListLinkFixerPlugin,
-  localLinksRehypePlugin,
-  workflowDiagramLinkFixerPlugin,
-  prerequisitesLinkFixerPlugin,
-  recmaInjectMdxDataPlugin,
-} from "remark-rehype-plugins"
-import MDXComponents from "@/components/MDXComponents"
-import mdxOptions from "../../../mdx-options.mjs"
-import { filesMap } from "../../../generated/files-map.mjs"
-import { Metadata } from "next"
 import { cache, Suspense } from "react"
 import { Loading } from "docs-ui"
+import path from "path"
+import fs from "fs/promises"
+import { ReferenceMDX } from "../../../components/ReferenceMDX"
+import { Metadata } from "next"
+import { getFrontMatterFromString } from "docs-utils"
 
 type PageProps = {
   params: Promise<{
@@ -27,60 +16,10 @@ export default async function ReferencesPage(props: PageProps) {
   const params = await props.params
   const { slug } = params
 
-  const fileData = await loadFile(slug)
-
-  if (!fileData) {
-    return notFound()
-  }
-
-  const pluginOptions = {
-    filePath: fileData.path,
-    basePath: process.cwd(),
-  }
-
   return (
     <Suspense fallback={<Loading />}>
       <div className="animate animate-fadeIn">
-        <MDXRemote
-          source={fileData.content}
-          components={MDXComponents}
-          options={{
-            mdxOptions: {
-              rehypePlugins: [
-                ...mdxOptions.options.rehypePlugins,
-                [
-                  typeListLinkFixerPlugin,
-                  {
-                    ...pluginOptions,
-                    checkLinksType: "md",
-                  },
-                ],
-                [
-                  workflowDiagramLinkFixerPlugin,
-                  {
-                    ...pluginOptions,
-                    checkLinksType: "value",
-                  },
-                ],
-                [
-                  prerequisitesLinkFixerPlugin,
-                  {
-                    ...pluginOptions,
-                    checkLinksType: "value",
-                  },
-                ],
-                [localLinksRehypePlugin, pluginOptions],
-              ],
-              remarkPlugins: [...mdxOptions.options.remarkPlugins],
-              recmaPlugins: [
-                [
-                  recmaInjectMdxDataPlugin,
-                  { isRemoteMdx: true, mode: process.env.NODE_ENV },
-                ],
-              ],
-            },
-          }}
-        />
+        <ReferenceMDX slug={slug} />
       </div>
     </Suspense>
   )
@@ -89,11 +28,10 @@ export default async function ReferencesPage(props: PageProps) {
 export async function generateMetadata({
   params,
 }: PageProps): Promise<Metadata> {
-  // read route params
   const slug = (await params).slug
   const metadata: Metadata = {}
 
-  const fileData = await loadFile(slug)
+  const fileData = await loadReferencesFile(slug)
 
   if (!fileData) {
     return metadata
@@ -106,28 +44,26 @@ export async function generateMetadata({
   }
 
   metadata.title = pageTitleMatch.groups.title
-  metadata.keywords = (fileData.source.frontmatter?.keywords || []) as string[]
+  const frontmatter = await getFrontMatterFromString(fileData.content)
+  metadata.keywords = (frontmatter.keywords || []) as string[]
 
   return metadata
 }
 
-const loadFile = cache(
-  async (
-    slug: string[]
-  ): Promise<
-    | {
-        content: string
-        source: MDXRemoteSerializeResult
-        path: string
-      }
-    | undefined
-  > => {
+export type LoadedReferenceFile = {
+  content: string
+  path: string
+}
+
+const loadReferencesFile = cache(
+  async (slug: string[]): Promise<LoadedReferenceFile | undefined> => {
     path.join(process.cwd(), "references")
     const monoRepoPath = path.resolve("..", "..", "..")
 
     const pathname = `/references/${slug.join("/")}`
-    const slugChanges = (await import("../../../generated/slug-changes.mjs"))
+    const slugChanges = (await import("@/generated/slug-changes.mjs"))
       .slugChanges
+    const filesMap = (await import("@/generated/files-map.mjs")).filesMap
     const fileDetails =
       slugChanges.find((f) => f.newSlug === pathname) ||
       filesMap.find((f) => f.pathname === pathname)
@@ -137,12 +73,9 @@ const loadFile = cache(
     const fullPath = path.join(monoRepoPath, fileDetails.filePath)
 
     const fileContent = await fs.readFile(fullPath, "utf-8")
-    const serialized = await serialize(fileContent, {
-      parseFrontmatter: true,
-    })
+
     return {
       content: fileContent,
-      source: serialized,
       path: fullPath,
     }
   }

www/apps/resources/components/ReferenceMDX/index.tsx

@@ -0,0 +1,33 @@
+"use client"
+
+import { MDXClientLazy, SerializeResult } from "next-mdx-remote-client/csr"
+import MDXComponents from "../MDXComponents"
+import { Loading, swrFetcher } from "docs-ui"
+import useSWR from "swr"
+import { config } from "../../config"
+import { notFound } from "next/navigation"
+
+type ReferenceMDXProps = {
+  slug: string[]
+}
+
+export const ReferenceMDX = ({ slug }: ReferenceMDXProps) => {
+  const {
+    data: serializedResult,
+    error,
+    isLoading,
+  } = useSWR<SerializeResult | { error: { name: string; message: string } }>(
+    `${config.basePath}/api/references/${slug.join("/")}`,
+    swrFetcher
+  )
+
+  if (isLoading || !serializedResult) {
+    return <Loading />
+  }
+
+  if ("error" in serializedResult || error) {
+    return notFound()
+  }
+
+  return <MDXClientLazy {...serializedResult} components={MDXComponents} />
+}

www/apps/resources/package.json

@@ -22,12 +22,14 @@
     "clsx": "^2.1.0",
     "docs-ui": "*",
     "next": "15.3.5",
+    "next-mdx-remote-client": "2",
     "posthog-js": "^1.269.1",
     "react": "rc",
     "react-dom": "rc",
     "rehype-mdx-code-props": "^2.0.0",
     "remark-directive": "^3.0.0",
-    "remark-frontmatter": "^5.0.0"
+    "remark-frontmatter": "^5.0.0",
+    "swr": "^2.3.6"
   },
   "devDependencies": {
     "@next/bundle-analyzer": "^15.3.5",