Fix rendering/router.subscribe race condition during hydration (#14497)

Author: brophdawg11

.changeset/calm-crabs-bathe.md

@@ -0,0 +1,5 @@
+---
+"react-router": patch
+---
+
+Fix a potential race condition that can occur when rendering a `HydrateFallback` and initial loaders land before the `router.subscribe` call happens in the `RouterProvider` layout effect

packages/react-router/__tests__/dom/data-browser-router-test.tsx

@@ -561,6 +561,48 @@ function testDomRouter(
           </div>"
         `);
       });
+
+      it("handles race conditions if router initialization completes prior to the layout effect router.subscribe() call", async () => {
+        const sleep = (ms: number) =>
+          new Promise((resolve) => setTimeout(resolve, ms));
+
+        // Kick off some async data load _before_ any react stuff
+        let suspensePromise = sleep(100).then(() => "DATA");
+
+        // Create a router that will initialize shortly after the suspense boundary resolves
+        let router = createTestRouter([
+          {
+            path: "/",
+            // Only fails when this is around 200ms - passes if you bump it to ~500ms
+            loader: () => sleep(200).then(() => "LOADER"),
+            Component: () => <p>Data:{useLoaderData()}</p>,
+            HydrateFallback: () => "Hydrate Fallback",
+          },
+        ]);
+        expect(router.state.initialized).toBe(false);
+
+        // Render a component that will suspend until `suspensePromise` resolves, then
+        // renders RouterProvider which sets up listeners for the router state
+        function App() {
+          // @ts-expect-error Needs React 19 types
+          React.use(suspensePromise);
+          return <RouterProvider router={router} />;
+        }
+
+        // Needs to be wrapped in `act()` for suspense to work properly
+        // https://github.com/testing-library/react-testing-library/issues/1375
+        await act(async () => {
+          render(
+            <React.Suspense fallback="Suspense Fallback">
+              <App />
+            </React.Suspense>,
+          );
+        });
+
+        expect(screen.getByText("Suspense Fallback")).toBeDefined();
+        await waitFor(() => screen.getByText("Data:LOADER"));
+        expect(screen.queryByText("Suspense Fallback")).toBeNull();
+      });
     });
 
     describe("navigations", () => {

packages/react-router/lib/components.tsx

@@ -618,6 +618,20 @@ export function RouterProvider({
   // pick up on any render-driven redirects/navigations (useEffect/<Navigate>)
   React.useLayoutEffect(() => router.subscribe(setState), [router, setState]);
 
+  // Track race conditions where we finish initializing prior to the layout
+  // effect above running to register our listener.  If we manually detect a
+  // change in `state.initialized`, automatically sync state.
+  let initialized = state.initialized;
+  React.useLayoutEffect(() => {
+    if (!initialized && router.state.initialized) {
+      setState(router.state, {
+        deletedFetchers: [],
+        flushSync: false,
+        newErrors: null,
+      });
+    }
+  }, [initialized, setState, router.state]);
+
   // When we start a view transition, create a Deferred we can use for the
   // eventual "completed" render
   React.useEffect(() => {