fix: proper 404 handling for missing docs/examples

- Return null from fetchApiContents on 404 instead of throwing
- Handle ENOENT in local filesystem fetch
- Convert serialized isNotFound errors to proper notFound() in route loaders

Author: tannerlinsley

src/routes/$libraryId/$version.docs.$.tsx

@@ -8,25 +8,36 @@ import {
   createFileRoute,
   useLocation,
   getRouteApi,
+  isNotFound,
 } from '@tanstack/react-router'
 
 const docsRouteApi = getRouteApi('/$libraryId/$version/docs')
 
 export const Route = createFileRoute('/$libraryId/$version/docs/$')({
   staleTime: 1000 * 60 * 5,
-  loader: (ctx) => {
+  loader: async (ctx) => {
     const { _splat: docsPath, version, libraryId } = ctx.params
     const library = findLibrary(libraryId)
 
     if (!library) {
       throw notFound()
     }
 
-    return loadDocs({
-      repo: library.repo,
-      branch: getBranch(library, version),
-      docsPath: `${library.docsRoot || 'docs'}/${docsPath}`,
-    })
+    try {
+      return await loadDocs({
+        repo: library.repo,
+        branch: getBranch(library, version),
+        docsPath: `${library.docsRoot || 'docs'}/${docsPath}`,
+      })
+    } catch (error) {
+      const isNotFoundError =
+        isNotFound(error) ||
+        (error && typeof error === 'object' && 'isNotFound' in error)
+      if (isNotFoundError) {
+        throw notFound()
+      }
+      throw error
+    }
   },
   head: ({ loaderData, params }) => {
     const { libraryId } = params

src/routes/$libraryId/$version.docs.framework.$framework.examples.$.tsx

@@ -1,4 +1,4 @@
-import { createFileRoute } from '@tanstack/react-router'
+import { createFileRoute, isNotFound, notFound } from '@tanstack/react-router'
 import {
   queryOptions,
   useQuery,
@@ -62,35 +62,49 @@ export const Route = createFileRoute(
     // Used to tell the github contents api where to start looking for files in the target repository
     const repoStartingDirPath = `examples/${examplePath}`
 
-    // Fetching and Caching the contents of the target directory
-    const githubContents = await queryClient.ensureQueryData(
-      repoDirApiContentsQueryOptions(library.repo, branch, repoStartingDirPath),
-    )
-
-    // Used to determine the starting file name for the explorer
-    // It's either the selected path in the search params or a default we can derive
-    // i.e. app.tsx, main.tsx, src/routes/__root.tsx, etc.
-    // This value is not absolutely guaranteed to be available, so further resolution may be necessary
-    const explorerCandidateStartingFileName =
-      path ||
-      getExampleStartingPath(params.framework as Framework, params.libraryId)
-
-    // Using the fetched contents, get the actual starting file-path for the explorer
-    // The `explorerCandidateStartingFileName` is used for matching, but the actual file-path may differ
-    const currentPath = determineStartingFilePath(
-      githubContents,
-      explorerCandidateStartingFileName,
-      params.framework as Framework,
-      params.libraryId,
-    )
-
-    // Now that we've resolved the starting file path, we can
-    // fetching and caching the file content for the starting file path
-    await queryClient.ensureQueryData(
-      fileQueryOptions(library.repo, branch, currentPath),
-    )
-
-    return { repoStartingDirPath, currentPath }
+    try {
+      // Fetching and Caching the contents of the target directory
+      const githubContents = await queryClient.ensureQueryData(
+        repoDirApiContentsQueryOptions(
+          library.repo,
+          branch,
+          repoStartingDirPath,
+        ),
+      )
+
+      // Used to determine the starting file name for the explorer
+      // It's either the selected path in the search params or a default we can derive
+      // i.e. app.tsx, main.tsx, src/routes/__root.tsx, etc.
+      // This value is not absolutely guaranteed to be available, so further resolution may be necessary
+      const explorerCandidateStartingFileName =
+        path ||
+        getExampleStartingPath(params.framework as Framework, params.libraryId)
+
+      // Using the fetched contents, get the actual starting file-path for the explorer
+      // The `explorerCandidateStartingFileName` is used for matching, but the actual file-path may differ
+      const currentPath = determineStartingFilePath(
+        githubContents,
+        explorerCandidateStartingFileName,
+        params.framework as Framework,
+        params.libraryId,
+      )
+
+      // Now that we've resolved the starting file path, we can
+      // fetching and caching the file content for the starting file path
+      await queryClient.ensureQueryData(
+        fileQueryOptions(library.repo, branch, currentPath),
+      )
+
+      return { repoStartingDirPath, currentPath }
+    } catch (error) {
+      const isNotFoundError =
+        isNotFound(error) ||
+        (error && typeof error === 'object' && 'isNotFound' in error)
+      if (isNotFoundError) {
+        throw notFound()
+      }
+      throw error
+    }
   },
   head: ({ params }) => {
     const library = getLibrary(params.libraryId)

src/utils/docs.ts

@@ -103,6 +103,10 @@ export const fetchRepoDirectoryContents = createServerFn({
   .handler(async ({ data: { repo, branch, startingPath } }) => {
     const githubContents = await fetchApiContents(repo, branch, startingPath)
 
+    if (!githubContents) {
+      throw notFound()
+    }
+
     // Cache for 60 minutes on shared cache
     // Revalidate in the background
     setResponseHeader('Cache-Control', 'public, max-age=0, must-revalidate')

src/utils/documents.server.ts

@@ -466,23 +466,38 @@ async function fetchApiContentsFs(
   async function getContentsForPath(
     filePath: string,
   ): Promise<Array<GitHubFile>> {
-    const list = await fsp.readdir(filePath, { withFileTypes: true })
-    return list
-      .filter((item) => !dirsAndFilesToIgnore.includes(item.name))
-      .map((item) => {
-        return {
-          name: item.name,
-          path: path.join(filePath, item.name),
-          type: item.isDirectory() ? 'dir' : 'file',
-          _links: {
-            self: path.join(filePath, item.name),
-          },
-        }
-      })
+    try {
+      const list = await fsp.readdir(filePath, { withFileTypes: true })
+      return list
+        .filter((item) => !dirsAndFilesToIgnore.includes(item.name))
+        .map((item) => {
+          return {
+            name: item.name,
+            path: path.join(filePath, item.name),
+            type: item.isDirectory() ? 'dir' : 'file',
+            _links: {
+              self: path.join(filePath, item.name),
+            },
+          }
+        })
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        'code' in error &&
+        error.code === 'ENOENT'
+      ) {
+        return []
+      }
+      throw error
+    }
   }
 
   const data = await getContentsForPath(fsStartPath)
 
+  if (data.length === 0) {
+    return null
+  }
+
   async function buildFileTree(
     nodes: Array<GitHubFile> | undefined,
     depth: number,
@@ -539,6 +554,9 @@ async function fetchApiContentsRemote(
   )
 
   if (!res.ok) {
+    if (res.status === 404) {
+      return null
+    }
     throw new Error(
       `Failed to fetch repo contents for ${repo}/${branch}/${startingPath}: Status is ${res.statusText} - ${res.status}`,
     )