fix(nextjs): make the deferred post-setActive refresh fire-and-forget

Awaiting the deferred refresh made setActive block on unrelated
long-running transitions: the empty transition used to detect settling
cannot finish while an app-held transition is pending, which broke the
pinned behavior that auth state changes apply immediately mid-transition
(transitions.test.ts).

The refresh is now requested via a window-stored pending flag and
dispatched by whichever hook instance observes transitions settling, so
nothing awaits it (restoring onAfterSetActive's original void contract)
and a request survives ClerkProvider remounts instead of resolving
without ever running.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: manovotny

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -13,8 +13,8 @@ import { RouterTelemetry } from '../../utils/router-telemetry';
 import { invalidateCacheAction } from '../server-actions';
 import { ClerkScripts } from './ClerkScripts';
 import { useAwaitablePush } from './useAwaitablePush';
-import { useAwaitableRefresh } from './useAwaitableRefresh';
 import { useAwaitableReplace } from './useAwaitableReplace';
+import { useDeferredRefresh } from './useDeferredRefresh';
 
 /**
  * LazyCreateKeylessApplication should only be loaded if the conditions below are met.
@@ -28,7 +28,7 @@ const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderPr
   const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_scriptsSlot, children } = props;
   const push = useAwaitablePush();
   const replace = useAwaitableReplace();
-  const refresh = useAwaitableRefresh();
+  const refresh = useDeferredRefresh();
 
   useSafeLayoutEffect(() => {
     window.__internal_onBeforeSetActive = intent => {
@@ -72,10 +72,10 @@ const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderPr
     window.__internal_onAfterSetActive = () => {
       if (__internal_invokeMiddlewareOnAuthStateChange) {
         // Deferred until in-flight transitions settle, so the refresh is never dispatched while a
-        // server-redirect follow-up navigation is still pending (which wedges the App Router, #9405)
-        return refresh();
+        // server-redirect follow-up navigation is still pending (which wedges the App Router, #9405).
+        // Fire-and-forget: setActive must not block on unrelated long-running transitions.
+        refresh();
       }
-      return undefined;
     };
   }, []);
 

packages/nextjs/src/app-router/client/__tests__/useAwaitableRefresh.test.tsx

@@ -0,0 +1,118 @@
+import { act, cleanup, render, waitFor } from '@testing-library/react';
+import React from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useDeferredRefresh } from '../useDeferredRefresh';
+
+const mockRefresh = vi.fn();
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ refresh: mockRefresh }),
+}));
+
+let currentRefresh: (() => void) | undefined;
+
+const Harness = () => {
+  currentRefresh = useDeferredRefresh();
+  return null;
+};
+
+const refresh = () => {
+  if (!currentRefresh) {
+    throw new Error('refresh function is not initialized');
+  }
+  currentRefresh();
+};
+
+describe('useDeferredRefresh', () => {
+  beforeEach(() => {
+    currentRefresh = undefined;
+    window.__clerk_internal_refresh = undefined;
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('dispatches router.refresh once transitions settle', async () => {
+    render(<Harness />);
+
+    act(() => {
+      refresh();
+    });
+
+    await waitFor(() => {
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('coalesces concurrent requests into a single router.refresh', async () => {
+    render(<Harness />);
+
+    act(() => {
+      refresh();
+      refresh();
+    });
+
+    await waitFor(() => {
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('does not call router.refresh when nothing was requested', async () => {
+    render(<Harness />);
+
+    // Give the isPending effect a chance to run on mount
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(mockRefresh).not.toHaveBeenCalled();
+  });
+
+  it('dispatches a refresh left pending by a previous instance on mount', async () => {
+    window.__clerk_internal_refresh = { pending: true };
+
+    render(<Harness />);
+
+    await waitFor(() => {
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+    expect(window.__clerk_internal_refresh?.pending).toBe(false);
+  });
+
+  it('preserves a refresh requested after unmount for the next instance', async () => {
+    const { unmount } = render(<Harness />);
+    unmount();
+
+    // Request while no instance is mounted (e.g. ClerkProvider remounting during a navigation)
+    refresh();
+    expect(window.__clerk_internal_refresh?.pending).toBe(true);
+    expect(mockRefresh).not.toHaveBeenCalled();
+
+    render(<Harness />);
+
+    await waitFor(() => {
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('allows a fresh refresh after a previous dispatch', async () => {
+    render(<Harness />);
+
+    act(() => {
+      refresh();
+    });
+    await waitFor(() => {
+      expect(mockRefresh).toHaveBeenCalledTimes(1);
+    });
+
+    act(() => {
+      refresh();
+    });
+    await waitFor(() => {
+      expect(mockRefresh).toHaveBeenCalledTimes(2);
+    });
+  });
+});

packages/nextjs/src/app-router/client/__tests__/useDeferredRefresh.test.tsx

@@ -9,59 +9,47 @@ const getClerkRefreshObject = () => {
 };
 
 /**
- * Returns an "awaitable" `router.refresh()` that waits for React's in-flight transitions to settle
- * before dispatching the refresh.
+ * Returns a fire-and-forget `router.refresh()` that waits for React's in-flight transitions to
+ * settle before dispatching the refresh.
  *
  * Dispatching a refresh synchronously after an awaitable navigation resolves can permanently wedge
  * the App Router: when the pushed route's Server Component calls `redirect()`, Next follows it with
  * a second navigation dispatched from its redirect boundary, and a refresh dispatched while that
  * follow-up is in flight can end up appended behind a discarded entry in Next's router action
- * queue. It then never runs, and the unresolved state promise it handed to React suspends the
- * router forever.
+ * queue (fixed upstream in next@16.3.0, broken in 15.5.1 through 16.2.x). It then never runs, and
+ * the unresolved state promise it handed to React suspends the router forever.
  *
  * An empty transition started here cannot settle while another transition (such as the redirect
  * follow-up navigation) is still rendering, so waiting for `isPending` to flip back guarantees the
  * refresh is dispatched onto an idle action queue.
+ *
+ * The returned function is intentionally not awaitable: a long-running app transition (e.g. a
+ * suspended `startTransition` held open by userland code) delays the refresh, and callers such as
+ * `setActive` must not block on it. The pending request lives on `window` so it survives
+ * `ClerkProvider` remounts; the next mounted instance dispatches it.
  */
-export const useAwaitableRefresh = (): (() => Promise<void>) => {
+export const useDeferredRefresh = (): (() => void) => {
   const router = useRouter();
   const [isPending, startTransition] = useTransition();
 
   if (typeof window !== 'undefined') {
     getClerkRefreshObject().fun = () => {
-      return new Promise<void>(res => {
-        // The buffer lives on window so a pending refresh survives ClerkProvider
-        // being unmounted and remounted during navigations.
-        const refresh = getClerkRefreshObject();
-        refresh.promisesBuffer ??= [];
-        refresh.promisesBuffer.push(res);
-        startTransition(() => {
-          // Intentionally empty: used only to observe when in-flight transitions settle.
-        });
+      getClerkRefreshObject().pending = true;
+      startTransition(() => {
+        // Intentionally empty: used only to observe when in-flight transitions settle.
       });
     };
   }
 
-  const flushPromises = () => {
-    const refresh = getClerkRefreshObject();
-    refresh.promisesBuffer?.forEach(resolve => resolve());
-    refresh.promisesBuffer = [];
-  };
-
-  // Resolve any pending promises on unmount so callers awaiting a refresh are never left hanging
-  useEffect(() => {
-    return flushPromises;
-  }, []);
-
   useEffect(() => {
-    if (!isPending && getClerkRefreshObject().promisesBuffer?.length) {
+    if (!isPending && getClerkRefreshObject().pending) {
+      getClerkRefreshObject().pending = false;
       router.refresh();
-      flushPromises();
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [isPending]);
 
   return useCallback(() => {
-    return getClerkRefreshObject().fun?.() ?? Promise.resolve();
+    getClerkRefreshObject().fun?.();
   }, []);
 };

…app-router/client/useAwaitableRefresh.ts …/app-router/client/useDeferredRefresh.tspackages/nextjs/src/app-router/client/useAwaitableRefresh.ts renamed to packages/nextjs/src/app-router/client/useDeferredRefresh.ts packages/nextjs/src/app-router/client/useAwaitableRefresh.ts renamed to packages/nextjs/src/app-router/client/useDeferredRefresh.ts

@@ -39,8 +39,8 @@ interface Window {
   __clerk_nav_await: Array<(value: void) => void>;
   __clerk_nav: (to: string) => Promise<void>;
   __clerk_internal_refresh?: {
-    fun?: () => Promise<void>;
-    promisesBuffer?: Array<() => void>;
+    fun?: () => void;
+    pending?: boolean;
   };
 
   __internal_onBeforeSetActive: (intent?: 'sign-out') => void | Promise<void>;