Show a loading spinner throughout the entire app boot sequence

nbudin · claude · nbudin · commit aebc7fac3930 · 2026-06-03T20:30:46.000-07:00
- Inline CSS spinner in the HTML shell so something appears immediately,
  even before the JS bundle downloads
- RouterLoadingOverlay component that stays visible until
  router.state.initialized is true, bridging the gap between the
  bootstrap Suspense phase and route components rendering
- app_root_loading_content helper in ApplicationHelper (included by both
  the ERB layout and CmsRenderingContext) so the inline spinner is
  rendered consistently in both paths

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/app/helpers/application_helper.rb b/app/helpers/application_helper.rb
@@ -31,6 +31,21 @@ def url_with_possible_host(path, host)
     "#{request.scheme}://#{host}#{path}"
   end
 
+  def app_root_loading_content
+    visually_hidden_style =
+      "position:absolute;width:1px;height:1px;padding:0;margin:-1px;" \
+        "overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0"
+    spinner_style =
+      "display:inline-block;width:2rem;height:2rem;border:0.25em solid currentColor;" \
+        "border-right-color:transparent;border-radius:50%;animation:_intercode_spinner 0.75s linear infinite"
+
+    tag.style("@keyframes _intercode_spinner{to{transform:rotate(360deg)}}") +
+      tag.div(
+        tag.div(tag.span("Loading...", style: visually_hidden_style), role: "status", style: spinner_style),
+        style: "text-align:center;margin-top:3rem"
+      )
+  end
+
   def browser_warning
     # CloudFront strips all cookies before forwarding to the origin, so the
     # suppressBrowserWarning cookie is never visible to Rails on proxied requests.
diff --git a/app/javascript/packs/application.tsx b/app/javascript/packs/application.tsx
@@ -1,7 +1,7 @@
 import 'regenerator-runtime/runtime';
 
 import mountReactComponents from '../mountReactComponents';
-import { StrictMode, Suspense, use, useMemo } from 'react';
+import { StrictMode, Suspense, use, useLayoutEffect, useMemo, useState } from 'react';
 import AuthenticityTokensManager, { getAuthenticityTokensURL } from 'AuthenticityTokensContext';
 import { createBrowserRouter, RouterContextProvider, RouterProvider } from 'react-router';
 import { buildBrowserApolloClient, GraphQLNotAuthenticatedErrorEvent } from 'useIntercodeApolloClient';
@@ -70,6 +70,35 @@ const bootstrapPromise: Promise<Bootstrap> = (async () => {
   return { clientConfiguration, authenticityTokensManager, authManager, client };
 })();
 
+type BrowserRouter = ReturnType<typeof createBrowserRouter>;
+
+// createBrowserRouter calls router.initialize() internally, which starts the
+// initial navigation asynchronously. By the time our useEffect subscribes,
+// the navigation may already be done — router.subscribe fires the callback
+// synchronously (via a buffered state update) with the final state. Watching
+// router.state.initialized (set to true once initial data loading completes)
+// handles both "already done" and "still in progress" correctly.
+function RouterLoadingOverlay({ router }: { router: BrowserRouter }) {
+  const [ready, setReady] = useState(() => router.state.initialized);
+
+  useLayoutEffect(() => {
+    return router.subscribe((state) => {
+      if (state.initialized) {
+        setReady(true);
+      }
+    });
+  }, [router]);
+
+  if (ready) return null;
+
+  return (
+    <div className="text-center mt-5 custom-loading-indicator">
+      <div className="spinner-border" role="status" />
+      <span className="visually-hidden">Loading...</span>
+    </div>
+  );
+}
+
 function DataModeApplicationEntry() {
   const bootstrap = use(bootstrapPromise);
 
@@ -101,6 +130,7 @@ function DataModeApplicationEntry() {
   return (
     <StrictMode>
       <AuthenticationManagerContext.Provider value={bootstrap.authManager}>
+        <RouterLoadingOverlay router={router} />
         <RouterProvider router={router} />
       </AuthenticationManagerContext.Provider>
     </StrictMode>
diff --git a/app/presenters/cms_rendering_context.rb b/app/presenters/cms_rendering_context.rb
@@ -65,7 +65,8 @@ def render_app_root_content(cms_layout, assigns)
     doc = Nokogiri::HTML.parse("<!DOCTYPE html><html><head>#{assigns["content_for_head"]}</head><body></body></html>")
     doc.xpath("//body/*").remove
     doc.xpath("//body").first.inner_html =
-      (assigns["browser_warning"] || "") + NOSCRIPT_WARNING + tag.div("", "data-react-class" => "AppRoot")
+      (assigns["browser_warning"] || "") + NOSCRIPT_WARNING +
+        tag.div(app_root_loading_content, "data-react-class" => "AppRoot")
     doc.to_s.html_safe # rubocop:disable Rails/OutputSafety
   rescue StandardError => e
     ErrorReporting.warn(e)
diff --git a/app/views/layouts/cdn_spa_shell.html.erb b/app/views/layouts/cdn_spa_shell.html.erb
@@ -28,6 +28,6 @@
 </head>
 <body>
   <%= CmsRenderingContext::NOSCRIPT_WARNING %>
-  <div data-react-class="AppRoot"></div>
+  <div data-react-class="AppRoot"><%= app_root_loading_content %></div>
 </body>
 </html>
