feat(admin): handle dynamic chunk load errors with auto reload

Author: Innei

apps/admin/src/bootstrap/register-chunk-error-handler.ts

@@ -0,0 +1,26 @@
+import { isChunkLoadError, notifyChunkError } from '~/utils/chunk-error'
+
+export function registerChunkErrorHandler(): void {
+  if (typeof window === 'undefined') return
+
+  window.addEventListener('vite:preloadError', (event) => {
+    if (isChunkLoadError((event as any).payload)) {
+      event.preventDefault()
+      notifyChunkError()
+    }
+  })
+
+  window.addEventListener('unhandledrejection', (event) => {
+    if (isChunkLoadError(event.reason)) {
+      event.preventDefault()
+      notifyChunkError()
+    }
+  })
+
+  window.addEventListener('error', (event) => {
+    if (isChunkLoadError(event.error ?? event.message)) {
+      event.preventDefault()
+      notifyChunkError()
+    }
+  })
+}

apps/admin/src/main.tsx

@@ -5,8 +5,10 @@ import { createRoot } from 'react-dom/client'
 
 import App from './App'
 import { migrateLegacyProviderType } from './bootstrap/migrate-legacy-provider-type'
+import { registerChunkErrorHandler } from './bootstrap/register-chunk-error-handler'
 
 migrateLegacyProviderType()
+registerChunkErrorHandler()
 
 const appRoot = createRootElement()
 

apps/admin/src/utils/chunk-error.ts

@@ -0,0 +1,36 @@
+import { toast } from 'sonner'
+
+const CHUNK_ERROR_PATTERNS = [
+  'Failed to fetch dynamically imported module',
+  'error loading dynamically imported module',
+  'Importing a module script failed',
+  'Failed to load module script',
+  'Loading chunk',
+  'Loading CSS chunk',
+  'ChunkLoadError',
+]
+
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error) return false
+
+  const name = (error as Error).name ?? ''
+  const message = (error as Error).message ?? String(error)
+  const combined = `${name} ${message}`
+
+  return CHUNK_ERROR_PATTERNS.some((p) => combined.includes(p))
+}
+
+const RELOAD_KEY = 'mx-admin-chunk-reload'
+
+export function notifyChunkError(): void {
+  const reloaded = sessionStorage.getItem(RELOAD_KEY)
+  if (reloaded) {
+    sessionStorage.removeItem(RELOAD_KEY)
+    toast.error(
+      'A new version of the admin is available. Please refresh the page to update.',
+    )
+    return
+  }
+  sessionStorage.setItem(RELOAD_KEY, '1')
+  window.location.reload()
+}