Skip to content

Commit 3611e9c

Browse files
manovotnyclaude
andcommitted
fix(nextjs): defer the post-setActive refresh until router transitions settle
Clerk's post-auth navigation into a route whose Server Component calls redirect() wedged the App Router on the intermediate route. The refresh dispatched from __internal_onAfterSetActive landed while Next was still following the redirect, got appended behind a discarded entry in the router action queue, and never ran — leaving React suspended on its unresolved state promise. ClerkProvider now routes that refresh through useAwaitableRefresh, which starts an empty transition and dispatches router.refresh() only once isPending settles, so the refresh always reaches an idle action queue. Fixes #9405 Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 5e5fe0d commit 3611e9c

5 files changed

Lines changed: 211 additions & 3 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@clerk/nextjs': patch
3+
---
4+
5+
Fix the App Router hanging on the intermediate route after Clerk's post-authentication navigation lands on a page whose Server Component calls `redirect()`. `ClerkProvider` now waits for in-flight route transitions to settle before dispatching its post-`setActive` `router.refresh()`, so the refresh is no longer lost inside Next.js' router action queue while the server redirect is being followed.

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
import { InternalClerkProvider as ReactClerkProvider, type Ui } from '@clerk/react/internal';
33
import { InitialStateProvider } from '@clerk/shared/react';
44
import dynamic from 'next/dynamic';
5-
import { useRouter } from 'next/navigation';
65
import React from 'react';
76

87
import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
@@ -14,6 +13,7 @@ import { RouterTelemetry } from '../../utils/router-telemetry';
1413
import { invalidateCacheAction } from '../server-actions';
1514
import { ClerkScripts } from './ClerkScripts';
1615
import { useAwaitablePush } from './useAwaitablePush';
16+
import { useAwaitableRefresh } from './useAwaitableRefresh';
1717
import { useAwaitableReplace } from './useAwaitableReplace';
1818

1919
/**
@@ -26,9 +26,9 @@ const LazyCreateKeylessApplication = dynamic(() =>
2626

2727
const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderProps<TUi>) => {
2828
const { __internal_invokeMiddlewareOnAuthStateChange = true, __internal_scriptsSlot, children } = props;
29-
const router = useRouter();
3029
const push = useAwaitablePush();
3130
const replace = useAwaitableReplace();
31+
const refresh = useAwaitableRefresh();
3232

3333
useSafeLayoutEffect(() => {
3434
window.__internal_onBeforeSetActive = intent => {
@@ -71,8 +71,11 @@ const NextClientClerkProvider = <TUi extends Ui = Ui>(props: NextClerkProviderPr
7171

7272
window.__internal_onAfterSetActive = () => {
7373
if (__internal_invokeMiddlewareOnAuthStateChange) {
74-
return router.refresh();
74+
// Deferred until in-flight transitions settle, so the refresh is never dispatched while a
75+
// server-redirect follow-up navigation is still pending (which wedges the App Router, #9405)
76+
return refresh();
7577
}
78+
return undefined;
7679
};
7780
}, []);
7881

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
import { act, cleanup, render, waitFor } from '@testing-library/react';
2+
import React from 'react';
3+
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
4+
5+
import { useAwaitableRefresh } from '../useAwaitableRefresh';
6+
7+
const mockRefresh = vi.fn();
8+
9+
vi.mock('next/navigation', () => ({
10+
useRouter: () => ({ refresh: mockRefresh }),
11+
}));
12+
13+
let currentRefresh: (() => Promise<void>) | undefined;
14+
15+
const Harness = () => {
16+
currentRefresh = useAwaitableRefresh();
17+
return null;
18+
};
19+
20+
const refresh = () => {
21+
if (!currentRefresh) {
22+
throw new Error('refresh function is not initialized');
23+
}
24+
return currentRefresh();
25+
};
26+
27+
describe('useAwaitableRefresh', () => {
28+
beforeEach(() => {
29+
currentRefresh = undefined;
30+
window.__clerk_internal_refresh = undefined;
31+
vi.clearAllMocks();
32+
});
33+
34+
afterEach(() => {
35+
cleanup();
36+
});
37+
38+
it('dispatches router.refresh once transitions settle and resolves the promise', async () => {
39+
render(<Harness />);
40+
41+
let promise!: Promise<void>;
42+
act(() => {
43+
promise = refresh();
44+
});
45+
46+
await waitFor(() => {
47+
expect(mockRefresh).toHaveBeenCalledTimes(1);
48+
});
49+
50+
await expect(promise).resolves.toBeUndefined();
51+
});
52+
53+
it('coalesces concurrent refresh calls into a single router.refresh', async () => {
54+
render(<Harness />);
55+
56+
let firstPromise!: Promise<void>;
57+
let secondPromise!: Promise<void>;
58+
59+
act(() => {
60+
firstPromise = refresh();
61+
secondPromise = refresh();
62+
});
63+
64+
await expect(Promise.all([firstPromise, secondPromise])).resolves.toEqual([undefined, undefined]);
65+
expect(mockRefresh).toHaveBeenCalledTimes(1);
66+
});
67+
68+
it('does not call router.refresh when nothing was requested', async () => {
69+
render(<Harness />);
70+
71+
// Give the isPending effect a chance to run on mount
72+
await act(async () => {
73+
await Promise.resolve();
74+
});
75+
76+
expect(mockRefresh).not.toHaveBeenCalled();
77+
});
78+
79+
it('refreshes and resolves a stale buffer left by a previous instance on mount', async () => {
80+
let resolved = false;
81+
window.__clerk_internal_refresh = {
82+
promisesBuffer: [
83+
() => {
84+
resolved = true;
85+
},
86+
],
87+
};
88+
89+
render(<Harness />);
90+
91+
await waitFor(() => {
92+
expect(mockRefresh).toHaveBeenCalledTimes(1);
93+
expect(resolved).toBe(true);
94+
});
95+
});
96+
97+
it('resolves pending promises on unmount', () => {
98+
const { unmount } = render(<Harness />);
99+
100+
let resolved = false;
101+
window.__clerk_internal_refresh!.promisesBuffer = [
102+
() => {
103+
resolved = true;
104+
},
105+
];
106+
107+
unmount();
108+
109+
expect(resolved).toBe(true);
110+
});
111+
112+
it('allows a fresh refresh after a previous flush', async () => {
113+
render(<Harness />);
114+
115+
let firstPromise!: Promise<void>;
116+
act(() => {
117+
firstPromise = refresh();
118+
});
119+
await expect(firstPromise).resolves.toBeUndefined();
120+
121+
let secondPromise!: Promise<void>;
122+
act(() => {
123+
secondPromise = refresh();
124+
});
125+
await expect(secondPromise).resolves.toBeUndefined();
126+
127+
expect(mockRefresh).toHaveBeenCalledTimes(2);
128+
});
129+
});
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
'use client';
2+
3+
import { useRouter } from 'next/navigation';
4+
import { useCallback, useEffect, useTransition } from 'react';
5+
6+
const getClerkRefreshObject = () => {
7+
window.__clerk_internal_refresh ??= {};
8+
return window.__clerk_internal_refresh;
9+
};
10+
11+
/**
12+
* Returns an "awaitable" `router.refresh()` that waits for React's in-flight transitions to settle
13+
* before dispatching the refresh.
14+
*
15+
* Dispatching a refresh synchronously after an awaitable navigation resolves can permanently wedge
16+
* the App Router: when the pushed route's Server Component calls `redirect()`, Next follows it with
17+
* a second navigation dispatched from its redirect boundary, and a refresh dispatched while that
18+
* follow-up is in flight can end up appended behind a discarded entry in Next's router action
19+
* queue. It then never runs, and the unresolved state promise it handed to React suspends the
20+
* router forever.
21+
*
22+
* An empty transition started here cannot settle while another transition (such as the redirect
23+
* follow-up navigation) is still rendering, so waiting for `isPending` to flip back guarantees the
24+
* refresh is dispatched onto an idle action queue.
25+
*/
26+
export const useAwaitableRefresh = (): (() => Promise<void>) => {
27+
const router = useRouter();
28+
const [isPending, startTransition] = useTransition();
29+
30+
if (typeof window !== 'undefined') {
31+
getClerkRefreshObject().fun = () => {
32+
return new Promise<void>(res => {
33+
// The buffer lives on window so a pending refresh survives ClerkProvider
34+
// being unmounted and remounted during navigations.
35+
const refresh = getClerkRefreshObject();
36+
refresh.promisesBuffer ??= [];
37+
refresh.promisesBuffer.push(res);
38+
startTransition(() => {
39+
// Intentionally empty: used only to observe when in-flight transitions settle.
40+
});
41+
});
42+
};
43+
}
44+
45+
const flushPromises = () => {
46+
const refresh = getClerkRefreshObject();
47+
refresh.promisesBuffer?.forEach(resolve => resolve());
48+
refresh.promisesBuffer = [];
49+
};
50+
51+
// Resolve any pending promises on unmount so callers awaiting a refresh are never left hanging
52+
useEffect(() => {
53+
return flushPromises;
54+
}, []);
55+
56+
useEffect(() => {
57+
if (!isPending && getClerkRefreshObject().promisesBuffer?.length) {
58+
router.refresh();
59+
flushPromises();
60+
}
61+
// eslint-disable-next-line react-hooks/exhaustive-deps
62+
}, [isPending]);
63+
64+
return useCallback(() => {
65+
return getClerkRefreshObject().fun?.() ?? Promise.resolve();
66+
}, []);
67+
};

‎packages/nextjs/src/global.d.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ interface Window {
3838
>;
3939
__clerk_nav_await: Array<(value: void) => void>;
4040
__clerk_nav: (to: string) => Promise<void>;
41+
__clerk_internal_refresh?: {
42+
fun?: () => Promise<void>;
43+
promisesBuffer?: Array<() => void>;
44+
};
4145

4246
__internal_onBeforeSetActive: (intent?: 'sign-out') => void | Promise<void>;
4347
__internal_onAfterSetActive: () => void | Promise<void>;

0 commit comments

Comments
 (0)