Merge pull request #11714 from neinteractiveliterature/boot-error-resilience

Catch boot/chunk-load failures instead of leaving a blank login page

Author: nbudin

app/javascript/BootErrorBoundary.tsx

@@ -0,0 +1,97 @@
+/* eslint-disable i18next/no-literal-string -- This boundary is the last line of
+   defense for a broken boot; it must not depend on i18n (which may be exactly
+   what failed to load), so its copy is intentionally hard-coded English. */
+import { Component, ErrorInfo, ReactNode, CSSProperties } from 'react';
+import { reloadOnAppEntrypointHeadersMismatch } from './checkAppEntrypointHeadersMatch';
+import errorReporting from 'ErrorReporting';
+
+// Guard against an auto-reload loop: if we reloaded very recently, show the
+// manual fallback instead of reloading again.
+const RELOAD_GUARD_KEY = 'intercode.bootErrorReloadAt';
+const RELOAD_GUARD_WINDOW_MS = 15_000;
+
+function reloadedWithinGuardWindow(): boolean {
+  try {
+    const last = Number(sessionStorage.getItem(RELOAD_GUARD_KEY));
+    return Number.isFinite(last) && last > 0 && Date.now() - last < RELOAD_GUARD_WINDOW_MS;
+  } catch {
+    return false;
+  }
+}
+
+function markReloadAttempt(): void {
+  try {
+    sessionStorage.setItem(RELOAD_GUARD_KEY, String(Date.now()));
+  } catch {
+    // sessionStorage may be unavailable (private mode / blocked); best effort.
+  }
+}
+
+const containerStyle: CSSProperties = {
+  maxWidth: '32rem',
+  margin: '4rem auto',
+  padding: '0 1rem',
+  fontFamily: 'system-ui, sans-serif',
+  textAlign: 'center',
+  lineHeight: 1.5,
+};
+
+const buttonStyle: CSSProperties = {
+  marginTop: '1rem',
+  padding: '0.5rem 1.25rem',
+  fontSize: '1rem',
+  cursor: 'pointer',
+};
+
+function BootErrorFallback() {
+  return (
+    <div style={containerStyle} role="alert">
+      <h1 style={{ fontSize: '1.25rem' }}>We couldn’t finish loading this page</h1>
+      <p>This is usually temporary and fixed by reloading. If it keeps happening, try again in a few minutes.</p>
+      <button type="button" style={buttonStyle} onClick={() => window.location.reload()}>
+        Reload the page
+      </button>
+    </div>
+  );
+}
+
+type Props = { children: ReactNode };
+type State = { hasError: boolean };
+
+// Catches failures during the SPA's initial boot/render — a rejected
+// bootstrapPromise, or an uncaught error rendering the route tree — that would
+// otherwise leave a blank white page with no recovery. A stale deploy (a chunk
+// hash that no longer exists) is the most common cause, so we try to reload
+// onto the fresh bundle; anything else gets a visible, reportable error instead
+// of a blank screen.
+export default class BootErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    try {
+      errorReporting().error(error, { tags: { context: 'boot' }, componentStack: info.componentStack });
+    } catch {
+      // Error reporting itself may be unavailable (e.g. its SDK was the chunk
+      // that failed to load); don't let that mask the fallback UI.
+    }
+
+    // Very often a blank boot is a stale deploy. If the deployed entrypoint has
+    // changed under this tab, reload to pick up the fresh bundle — but only if
+    // we didn't just try, so we never get stuck in a reload loop.
+    if (!reloadedWithinGuardWindow()) {
+      markReloadAttempt();
+      void reloadOnAppEntrypointHeadersMismatch();
+    }
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return <BootErrorFallback />;
+    }
+    return this.props.children;
+  }
+}

app/javascript/packs/application.tsx

@@ -3,7 +3,7 @@ import 'regenerator-runtime/runtime';
 import mountReactComponents from '../mountReactComponents';
 import { StrictMode, Suspense, use, useLayoutEffect, useMemo, useState } from 'react';
 import AuthenticityTokensManager, { getAuthenticityTokensURL } from 'AuthenticityTokensContext';
-import { createBrowserRouter, RouterContextProvider, RouterProvider } from 'react-router';
+import { createBrowserRouter, RouterContextProvider, RouterProvider, RouteObject } from 'react-router';
 import { buildBrowserApolloClient, GraphQLNotAuthenticatedErrorEvent } from 'useIntercodeApolloClient';
 import {
   apolloClientContext,
@@ -18,6 +18,8 @@ import { AuthenticationManager, AuthenticationManagerContext } from '../Authenti
 import { PageLoadingIndicator } from '@neinteractiveliterature/litform';
 import { ApolloClient } from '@apollo/client';
 import { initErrorReporting } from 'ErrorReporting';
+import { checkAppEntrypointHeadersOnError } from '../checkAppEntrypointHeadersMatch';
+import BootErrorBoundary from '../BootErrorBoundary';
 
 type Bootstrap = {
   clientConfiguration: ClientConfiguration;
@@ -118,19 +120,37 @@ function RouterLoadingOverlay({ router }: { router: BrowserRouter }) {
   );
 }
 
+// Wrap every route's lazy import so a failed chunk load — almost always a stale
+// deploy whose hashed chunk no longer exists — reloads onto the fresh bundle
+// instead of surfacing as an unrecoverable blank. Applied once to the whole tree.
+function withEntrypointReloadOnLazy(routes: RouteObject[]): RouteObject[] {
+  return routes.map((route) => {
+    let { lazy } = route;
+    if (typeof lazy === 'function') {
+      const load = lazy;
+      lazy = () => checkAppEntrypointHeadersOnError(load);
+    }
+    return {
+      ...route,
+      lazy,
+      children: route.children ? withEntrypointReloadOnLazy(route.children) : route.children,
+    } as RouteObject;
+  });
+}
+
 function DataModeApplicationEntry() {
   const bootstrap = use(bootstrapPromise);
 
   const router = useMemo(
     () =>
       createBrowserRouter(
-        [
+        withEntrypointReloadOnLazy([
           {
             id: 'root',
             lazy: () => import('root'),
             children: appRootRoutes,
           },
-        ],
+        ]),
         {
           getContext: () => {
             const context = new RouterContextProvider();
@@ -158,9 +178,11 @@ function DataModeApplicationEntry() {
 
 function DataModeApplicationEntrySuspenseWrapper() {
   return (
-    <Suspense fallback={<PageLoadingIndicator visible />}>
-      <DataModeApplicationEntry />
-    </Suspense>
+    <BootErrorBoundary>
+      <Suspense fallback={<PageLoadingIndicator visible />}>
+        <DataModeApplicationEntry />
+      </Suspense>
+    </BootErrorBoundary>
   );
 }
 

test/javascript/BootErrorBoundary.test.tsx

@@ -0,0 +1,36 @@
+import { vi } from 'vitest';
+import { render } from '@testing-library/react';
+import BootErrorBoundary from '../../app/javascript/BootErrorBoundary';
+
+function Boom(): never {
+  throw new Error('boom');
+}
+
+describe('BootErrorBoundary', () => {
+  it('renders its children when nothing throws', () => {
+    const { getByText } = render(
+      <BootErrorBoundary>
+        <div>app content</div>
+      </BootErrorBoundary>,
+    );
+
+    expect(getByText('app content')).toBeTruthy();
+  });
+
+  it('renders a reload fallback instead of a blank page when a child throws', () => {
+    // React logs caught boundary errors to console.error; silence it for this case.
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const { getByRole, queryByText } = render(
+        <BootErrorBoundary>
+          <Boom />
+        </BootErrorBoundary>,
+      );
+
+      expect(getByRole('button', { name: /reload/i })).toBeTruthy();
+      expect(queryByText('app content')).toBeNull();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+});