Handle stale chunk errors by reloading page after deployments (#8421)

* Handle stale chunk errors by reloading the page after deployments

When assets are redeployed with new content hashes, users with cached
pages get TypeError when dynamically imported chunks (React.lazy) no
longer exist on the CDN. This adds graceful recovery by detecting these
errors and triggering a page reload with loop prevention.

- Create chunk-load-error-handler utility with browser-variant detection
  (Chrome, Firefox, Safari all use different error messages)
- Add ErrorBoundary fallback in react-bootloader to catch chunk errors
  in the React tree and reload instead of showing blank components
- Add global unhandledrejection handler as safety net for failures
  outside the React error boundary tree
- Fix Sentry beforeSend filter to match all browser error variants
  (was only matching Chrome's "Failed to fetch dynamically imported module")
- Guard ErrorFallback auto-reset against chunk errors to prevent
  infinite retry loops

Closes #8369

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add retry logic for dynamic imports to handle transient failures

Old chunk files persist on the CDN, so import failures are transient
(network blips, CDN hiccups) rather than missing files. Instead of
immediately reloading the page, retry the import up to 3 times with
a 1-second delay between attempts.

- Create lazy-with-retry utility as drop-in replacement for React.lazy
- Update all 6 files that use lazy() to import from the retry utility
  (129 lazy call sites, only import lines change)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Handle chunk load errors at source to prevent Sentry propagation

After all retries are exhausted, if the error is a chunk load error,
reload the page directly instead of throwing. This ensures the error
never reaches Sentry.captureException via ErrorBoundary handlers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: iHiD

app/javascript/components/ErrorBoundary.tsx

@@ -7,6 +7,10 @@ import {
 } from 'react-error-boundary'
 import { APIError } from './types'
 import * as Sentry from '@sentry/react'
+import {
+  isChunkLoadError,
+  safeReloadForChunkError,
+} from '../utils/chunk-load-error-handler'
 
 const ERROR_MESSAGE_TIMEOUT_IN_MS = 500
 
@@ -60,10 +64,15 @@ export const ErrorFallback = ({
   resetErrorBoundary,
 }: FallbackProps): JSX.Element => {
   useEffect(() => {
+    if (isChunkLoadError(error)) {
+      safeReloadForChunkError()
+      return
+    }
+
     const timer = setTimeout(resetErrorBoundary, ERROR_MESSAGE_TIMEOUT_IN_MS)
 
     return () => clearTimeout(timer)
-  }, [resetErrorBoundary])
+  }, [error, resetErrorBoundary])
 
   return (
     <div>

app/javascript/components/editor/FileEditorCodeMirror.tsx

@@ -4,9 +4,9 @@ import React, {
   useState,
   useEffect,
   createContext,
-  lazy,
   Suspense,
 } from 'react'
+import { lazy } from '@/utils/lazy-with-retry'
 import { File } from '../types'
 import type { Handler } from '../misc/CodeMirror'
 import { Tab, TabContext } from '../common/Tab'

app/javascript/components/modals/BegModal.tsx

@@ -1,6 +1,7 @@
 // i18n-key-prefix: begModal
 // i18n-namespace: components/modals/BegModal.tsx
-import React, { lazy, Suspense, useCallback, useState } from 'react'
+import React, { Suspense, useCallback, useState } from 'react'
+import { lazy } from '@/utils/lazy-with-retry'
 import currency from 'currency.js'
 import { PaymentIntentType } from '@/components/donations/stripe-form/useStripeForm'
 import { Request } from '@/hooks/request-query'

app/javascript/components/modals/student/finish-mentor-discussion-modal/DonationStep.tsx

@@ -1,4 +1,5 @@
-import React, { lazy, Suspense } from 'react'
+import React, { Suspense } from 'react'
+import { lazy } from '@/utils/lazy-with-retry'
 import { MentoringSessionDonation } from '@/components/types'
 import currency from 'currency.js'
 import { DiscussionActionsLinks } from '@/components/student/mentoring-session/DiscussionActions'

app/javascript/packs/application.tsx

@@ -1,5 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import React, { lazy, Suspense } from 'react'
+import React, { Suspense } from 'react'
+import { lazy } from '@/utils/lazy-with-retry'
 import { camelizeKeys } from 'humps'
 import { camelizeKeysAs } from '@/utils/camelize-keys-as'
 import { initReact } from '@/utils/react-bootloader'

app/javascript/packs/bootcamp-js.tsx

@@ -1,5 +1,6 @@
 import React from 'react'
-import { lazy, Suspense } from 'react'
+import { Suspense } from 'react'
+import { lazy } from '@/utils/lazy-with-retry'
 import { initReact } from '../utils/react-bootloader'
 import '@hotwired/turbo-rails'
 import { camelizeKeysAs } from '@/utils/camelize-keys-as'

app/javascript/packs/internal.tsx

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 // Absolute, module imports
-import React, { Suspense, lazy } from 'react'
+import React, { Suspense } from 'react'
+import { lazy } from '@/utils/lazy-with-retry'
 import { camelizeKeys } from 'humps'
 import currency from 'currency.js'
 import { initReact } from '@/utils/react-bootloader'

app/javascript/utils/chunk-load-error-handler.ts

@@ -0,0 +1,41 @@
+const RELOAD_KEY = 'exercism:chunk-reload-timestamp'
+const RELOAD_COOLDOWN_MS = 10_000
+
+/**
+ * Detects dynamic import failures across all major browsers.
+ *
+ * Chrome/Edge: "Failed to fetch dynamically imported module: <url>"
+ * Firefox: "error loading dynamically imported module: <url>"
+ * Safari: "Importing a module script failed."
+ */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false
+  const msg = error.message.toLowerCase()
+  return (
+    msg.includes('failed to fetch dynamically imported module') ||
+    msg.includes('error loading dynamically imported module') ||
+    msg.includes('importing a module script failed')
+  )
+}
+
+/**
+ * Reloads the page to pick up new assets after a deployment,
+ * with sessionStorage-based cooldown to prevent infinite reload loops.
+ */
+export function safeReloadForChunkError(): void {
+  try {
+    const lastReload = sessionStorage.getItem(RELOAD_KEY)
+    const now = Date.now()
+
+    if (lastReload && now - parseInt(lastReload, 10) < RELOAD_COOLDOWN_MS) {
+      return
+    }
+
+    sessionStorage.setItem(RELOAD_KEY, String(now))
+  } catch {
+    // sessionStorage may be unavailable (private browsing, storage full).
+    // Reload anyway — worst case is one extra reload.
+  }
+
+  window.location.reload()
+}

app/javascript/utils/lazy-with-retry.ts

@@ -0,0 +1,40 @@
+import React from 'react'
+import {
+  isChunkLoadError,
+  safeReloadForChunkError,
+} from './chunk-load-error-handler'
+
+const MAX_RETRIES = 3
+const RETRY_DELAY_MS = 1000
+
+/**
+ * Drop-in replacement for React.lazy that retries the dynamic import
+ * on transient failures (network blips, CDN hiccups, etc.).
+ */
+export function lazy<T extends React.ComponentType<any>>(
+  factory: () => Promise<{ default: T }>
+): React.LazyExoticComponent<T> {
+  return React.lazy(() => retryImport(factory))
+}
+
+function retryImport<T extends React.ComponentType<any>>(
+  factory: () => Promise<{ default: T }>,
+  retriesLeft = MAX_RETRIES
+): Promise<{ default: T }> {
+  return factory().catch((error) => {
+    if (retriesLeft <= 0) {
+      if (isChunkLoadError(error)) {
+        safeReloadForChunkError()
+        return new Promise<{ default: T }>(() => {})
+      }
+      throw error
+    }
+
+    return new Promise<{ default: T }>((resolve) =>
+      setTimeout(
+        () => resolve(retryImport(factory, retriesLeft - 1)),
+        RETRY_DELAY_MS
+      )
+    )
+  })
+}

app/javascript/utils/react-bootloader.tsx

@@ -3,6 +3,10 @@ import { createRoot } from 'react-dom/client'
 import * as Sentry from '@sentry/react'
 import { ExercismTippy } from '../components/misc/ExercismTippy'
 import { QueryClientProvider } from '@tanstack/react-query'
+import {
+  isChunkLoadError,
+  safeReloadForChunkError,
+} from './chunk-load-error-handler'
 
 type ErrorBoundaryType = React.ComponentType<any>
 
@@ -26,12 +30,19 @@ if (process.env.SENTRY_DSN) {
     enabled: process.env.NODE_ENV === 'production',
     sendDefaultPii: false,
     beforeSend: (event) => {
-      // Drop non-actionable dynamic import failures (network issues, stale chunks)
-      const isDynamicImportError = event.exception?.values?.some(
-        (ex) =>
-          ex.value?.includes('Failed to fetch dynamically imported module') ||
-          ex.value?.includes('Importing a module script failed')
-      )
+      // Drop non-actionable dynamic import failures (network issues, stale chunks).
+      // Error messages vary by browser:
+      //   Chrome/Edge: "Failed to fetch dynamically imported module: <url>"
+      //   Firefox:     "error loading dynamically imported module: <url>"
+      //   Safari:      "Importing a module script failed."
+      const isDynamicImportError = event.exception?.values?.some((ex) => {
+        const msg = ex.value?.toLowerCase() || ''
+        return (
+          msg.includes('failed to fetch dynamically imported module') ||
+          msg.includes('error loading dynamically imported module') ||
+          msg.includes('importing a module script failed')
+        )
+      })
       if (isDynamicImportError) return null
 
       // Drop non-actionable Cloudflare Turnstile widget errors (browser extensions, privacy settings, etc.)
@@ -124,6 +135,22 @@ if (process.env.SENTRY_DSN) {
   ErrorBoundary = Sentry.ErrorBoundary
 }
 
+// Reload the page when a dynamic import fails due to stale chunks after deployment.
+// This catches failures that occur outside React's error boundary tree.
+window.addEventListener('unhandledrejection', (event) => {
+  if (isChunkLoadError(event.reason)) {
+    event.preventDefault()
+    safeReloadForChunkError()
+  }
+})
+
+const chunkErrorFallback: Sentry.FallbackRender = ({ error }) => {
+  if (isChunkLoadError(error)) {
+    safeReloadForChunkError()
+  }
+  return <></>
+}
+
 // Asynchronously appends a stylesheet to the head and resolves
 // the promise when it's finished loading.
 let loadStylesheet = function (url) {
@@ -314,7 +341,7 @@ const render = (elem: HTMLElement, component: React.ReactNode) => {
   root.render(
     <React.StrictMode>
       <QueryClientProvider client={window.queryClient}>
-        <ErrorBoundary>{component}</ErrorBoundary>
+        <ErrorBoundary fallback={chunkErrorFallback}>{component}</ErrorBoundary>
       </QueryClientProvider>
     </React.StrictMode>
   )