fix: handle chunk errors (#357)

Author: tmm

.changeset/calm-deer-wave.md

@@ -0,0 +1,5 @@
+---
+"vocs": patch
+---
+
+Added handling for "Failed to fetch dynamically imported module" errors, which can be caused by version skew.

src/app/index.client.tsx

@@ -5,6 +5,7 @@ import { hydrateRoot } from 'react-dom/client'
 import { createBrowserRouter, RouterProvider } from 'react-router'
 import { ConfigProvider, getConfig } from './hooks/useConfig.js'
 import { routes } from './routes.js'
+import { clearChunkReloadFlag } from './utils/chunkError.js'
 import { hydrateLazyRoutes } from './utils/hydrateLazyRoutes.js'
 import { removeTempStyles } from './utils/removeTempStyles.js'
 
@@ -15,6 +16,7 @@ async function hydrate() {
 
   await hydrateLazyRoutes(routes, basePath)
   removeTempStyles()
+  clearChunkReloadFlag()
 
   const router = createBrowserRouter(routes, { basename: basePath })
   hydrateRoot(

src/app/routes.tsx

@@ -4,25 +4,31 @@ import type { RouteObject } from 'react-router'
 import { NotFound } from './components/NotFound.js'
 import { DocsLayout } from './layouts/DocsLayout.js'
 import { Root } from './root.js'
+import { maybeHandleChunkError } from './utils/chunkError.js'
 
 const notFoundRoute = (() => {
   const virtualRoute = routes_virtual.find(({ path }) => path === '*')
   if (virtualRoute)
     return {
       path: virtualRoute.path,
       lazy: async () => {
-        const { frontmatter, ...route } = await virtualRoute.lazy()
+        try {
+          const { frontmatter, ...route } = await virtualRoute.lazy()
 
-        return {
-          ...route,
-          element: (
-            <Root frontmatter={frontmatter} path={virtualRoute.path}>
-              <DocsLayout>
-                <route.default />
-              </DocsLayout>
-            </Root>
-          ),
-        } satisfies RouteObject
+          return {
+            ...route,
+            element: (
+              <Root frontmatter={frontmatter} path={virtualRoute.path}>
+                <DocsLayout>
+                  <route.default />
+                </DocsLayout>
+              </Root>
+            ),
+          } satisfies RouteObject
+        } catch (error) {
+          maybeHandleChunkError(error as Error)
+          throw error
+        }
       },
     }
 
@@ -45,24 +51,29 @@ export const routes = [
     .map((route_virtual) => ({
       path: route_virtual.path,
       lazy: async () => {
-        const { frontmatter, ...route } = await route_virtual.lazy()
+        try {
+          const { frontmatter, ...route } = await route_virtual.lazy()
 
-        return {
-          ...route,
-          element: (
-            <Root
-              content={decodeURIComponent(route_virtual.content ?? '')}
-              filePath={route_virtual.filePath}
-              frontmatter={frontmatter}
-              lastUpdatedAt={route_virtual.lastUpdatedAt}
-              path={route_virtual.path}
-            >
-              <DocsLayout>
-                <route.default />
-              </DocsLayout>
-            </Root>
-          ),
-        } satisfies RouteObject
+          return {
+            ...route,
+            element: (
+              <Root
+                content={decodeURIComponent(route_virtual.content ?? '')}
+                filePath={route_virtual.filePath}
+                frontmatter={frontmatter}
+                lastUpdatedAt={route_virtual.lastUpdatedAt}
+                path={route_virtual.path}
+              >
+                <DocsLayout>
+                  <route.default />
+                </DocsLayout>
+              </Root>
+            ),
+          } satisfies RouteObject
+        } catch (error) {
+          maybeHandleChunkError(error as Error)
+          throw error
+        }
       },
     })),
   notFoundRoute,

src/app/utils/chunkError.ts

@@ -0,0 +1,26 @@
+export function isChunkError(error: Error) {
+  if (!error) return false
+  if (!error.message) return false
+  const message = error.message.toLowerCase()
+  return (
+    message.includes('failed to fetch dynamically imported module') || // Chrome
+    message.includes('error loading dynamically imported module') || // Firefox/Safari
+    message.includes('dynamically imported module') // fallback
+  )
+}
+
+export function maybeHandleChunkError(error: Error) {
+  if (!isChunkError(error)) return
+  if (sessionStorage.getItem(reloadKey)) {
+    sessionStorage.removeItem(reloadKey)
+    return
+  }
+  sessionStorage.setItem(reloadKey, 'true')
+  window.location.reload()
+}
+
+export function clearChunkReloadFlag() {
+  sessionStorage.removeItem(reloadKey)
+}
+
+const reloadKey = 'vocs.reload'

src/app/utils/hydrateLazyRoutes.ts

@@ -1,20 +1,27 @@
 import { matchRoutes, type RouteObject } from 'react-router'
 
+import { maybeHandleChunkError } from './chunkError.js'
+
 export async function hydrateLazyRoutes(routes: RouteObject[], basePath: string | undefined) {
   // Determine if any of the initial routes are lazy
   const lazyMatches = matchRoutes(routes, window.location, basePath)?.filter((m) => m.route.lazy)
 
   // Load the lazy matches and update the routes before creating your router
   // so we can hydrate the SSR-rendered content synchronously
-  if (lazyMatches && lazyMatches?.length > 0) {
-    await Promise.all(
-      lazyMatches.map(async (m) => {
-        const routeModule = typeof m.route.lazy === 'function' ? await m.route.lazy() : m.route.lazy
-        Object.assign(m.route, {
-          ...routeModule,
-          lazy: undefined,
-        })
-      }),
-    )
-  }
+  if (lazyMatches && lazyMatches?.length > 0)
+    try {
+      await Promise.all(
+        lazyMatches.map(async (m) => {
+          const routeModule =
+            typeof m.route.lazy === 'function' ? await m.route.lazy() : m.route.lazy
+          Object.assign(m.route, {
+            ...routeModule,
+            lazy: undefined,
+          })
+        }),
+      )
+    } catch (error) {
+      maybeHandleChunkError(error as Error)
+      throw error
+    }
 }