`@clerk/nextjs` with `cacheComponents`: after a root param change (`/en` → `/sk`), `Clerk.navigate()` within `/sk` never resolves
維護者通常 1 天內回覆
評估
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 新手友好度
- 35/100
- Issue 類型
- 缺陷
- 描述清晰度
- 描述清楚
- 活躍度
- 停滯
- 技術堆疊
- next.js, react, typescript
研究方向
Start with packages/nextjs/src/app-router/client/useInternalNavFun.ts and compare when its navigation function is saved during render with the proposed layout-effect approach. Reproduce the hang using the linked repro and its /en to /sk steps; check the existing cacheComponents sign-out tests mentioned in #7996. Done means Clerk.navigate() resolves after a language switch and the linked sign-in/sign-out cases no longer hang.
由索引模型根據 Issue 內容生成。
描述
Preliminary Checks
-
I have reviewed the documentation: https://clerk.com/docs
-
I have searched for existing issues: https://github.com/clerk/javascript/issues
-
I have not already reached out to Clerk support via email or Discord (if you have, no need to open an issue here)
-
This issue is not a question, general help request, or anything other than a bug report directly related to Clerk. Please ask questions in our Discord community: https://clerk.com/discord.
Reproduction
https://github.com/Joozty/clerk-nextjs-activity-repro
Publishable key
Not shared. The reproduction works with any development instance: put your own key in .env.local (see .env.example).
Description
With cacheComponents: true, a client-side navigation that changes a root param keeps the old root layout tree mounted, but hidden in <Activity>. For example, this happens when you click a link from /en to /sk with app/[lang]/layout.jsx. After that, a Clerk.navigate() call that stays in /sk never resolves. setActive() and signOut() wait for navigate(), so sign-in and sign-out can get stuck.
Steps to reproduce:
- Clone the reproduction and run
pnpm install. - Copy
.env.exampleto.env.local. Set the publishable key of your own development instance there. - Run
pnpm devand open http://localhost:3000/en. - Click Test Clerk.navigate(). It shows
resolved. - Click the
/sklink. Then click Test Clerk.navigate() again.
Expected behavior:
resolved, like in step 4.
Actual behavior:
still pending after 3 seconds. The promise never resolves. The button navigates to the current page, so the URL doesn't change.
pnpm buildandpnpm startgive the same result.partialPrefetching: falsegives the same result.- Without
cacheComponents, the promise resolves. (Remove bothcacheComponentsandpartialPrefetchingfromnext.config.mjs.) - On
/sk,await Clerk.navigate('/en')resolves, because it goes to the other language. It also resolves the promise that was stuck.
Why it happens:
- In the browser, Next.js puts the value of
[lang]in the Reactkeyof the segment. So/enand/skare two different React trees. WithcacheComponents, Next.js doesn't unmount the/entree. It hides the tree in<Activity>. Now twoClerkProviders are mounted. useInternalNavFun(packages/nextjs/src/app-router/client/useInternalNavFun.ts) saves its navigation function inwindow.__clerk_internal_navigations[name].funduring render.- The hidden tree still renders.
useRouter()fromnext/navigationreadsLayoutRouterContext, and Next.js gives this context a new value on every navigation. So after each navigation, the hiddenClerkProviderrenders after the visible one. Its function replaces the visible tree's function. - The hidden tree's function starts the navigation with the hidden tree's
startTransition. The promise resolves only when an effect runs: theisPendingeffect of the hidden tree, or the effect that runs when aClerkProvideris shown or hidden. React doesn't run effects in a hidden tree. So the promise resolves only when a navigation shows or hides a tree, for example/sk→/en. - Later calls with the same URL don't navigate at all, because
pendingDestinationis still that URL.
What users see:
I tested this with a real account:
- Open
/en, click/sk, and sign in with email in the modal. The sign-in gets stuck. Clerk creates the session, but the page shows no user button and no Sign in button until you reload. The modal goes back to the current page, sosetActive()waits for a navigation in the same language. - Open
/en, click/sk, click/en, and sign out. The sign-out gets stuck in the same way, becauseafterSignOutUrl(/en) is in the current language. - Open
/en, click/sk, and sign out. This sign-out finishes, but only because of a second bug (#10538): clerk-js keeps the firstafterSignOutUrl, so the sign-out goes to the other language,/en. - Sign-in with Google is not affected, because it comes back with a full page load.
- With the fix below, both stuck cases finish.
Possible fix:
Save fun in a layout effect instead of during render. React doesn't run layout effects in a hidden tree. When the tree becomes visible, React runs its layout effects again. So fun always belongs to the visible tree:
// useInternalNavFun.ts
import { useSafeLayoutEffect } from '../../client-boundary/hooks/useSafeLayoutEffect';
// Use this instead of the `if (windowNav) { … }` block:
useSafeLayoutEffect(() => {
if (windowNav) {
getClerkNavigationObject(name).fun = (to, opts) => {
// unchanged
};
}
});
The reproduction has this change as a pnpm patch. With the patch, Clerk.navigate() resolves after every language switch. The README explains how to apply the patch.
Related:
- #10538 is the second bug in the same reproduction:
afterSignOutUrlkeeps its first value. - #2899 and #3480 moved this navigation function to
windowand set it during render. This design expects only one mountedClerkProvider. - #7989 removed
usePathnamefrom this hook forcacheComponents. Since then, onlyisPendingor aClerkProviderthat mounts or unmounts resolves the waiting promises. - #7865 fixed another promise in this hook that never resolved, but the trigger was different: a second push to the same URL.
- #7996 added
cacheComponentssign-out tests, and #8071 skipped them becausetoBeSignedOut()timed out. They are still skipped onmain. That test app has one root layout without params, so the cause may be different. - #9987 also makes
setActive()andsignOut()hang, but the cause is different: there,onBeforeSetActivenever finishes. Its fix, #10088, doesn't changeuseInternalNavFun, so it won't fix this bug. - #9405 had a similar hang after sign-in, but #9406 traced it to a Next.js router bug that Next 16.3.0 fixed.
- vercel/next.js#86577 is the Next.js issue about
cacheComponentskeeping earlier routes, even the previous language, mounted in a hidden<Activity>. - pacocoursey/next-themes#375 is the same kind of bug in next-themes: after a language switch, the hidden
ThemeProviderof the old language writes a stale theme.
Environment
System:
OS: macOS 27.2
CPU: (10) arm64 Apple M4
Memory: 73.23 MB / 32.00 GB
Shell: 5.9 - /bin/zsh
Binaries:
Node: 24.15.0 - /Users/jozef/.volta/tools/image/node/24.15.0/bin/node
npm: 11.12.1 - /Users/jozef/.volta/tools/image/node/24.15.0/bin/npm
pnpm: 12.4.1 - /Users/jozef/.volta/bin/pnpm
Browsers:
Chrome: 156.0.8078.48
Firefox: 159.0
Safari: 27.2
npmPackages:
@clerk/nextjs: 7.9.22 => 7.9.22
next: 16.4.3 => 16.4.3
react: 19.3.0 => 19.3.0
react-dom: 19.3.0 => 19.3.0
Loaded from the Frontend API:
@clerk/clerk-js: 6.41.0 (6.42.0 and main have the same code)
@clerk/ui: 1.42.0
- 主要語言
- TypeScript
- 星號
- 1.8k
- 分支
- 492
- 平均合併
- 1 天 7 小時
- 30 天內合併 PR
- 357
環境準備
- 沒有 Dockerfile 或 Docker Compose 檔案
- 有 Pull Request 範本
- 閱讀貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
clerk/javascript 的其他 Issue
-
難度 2/5 1-3 小時 新手友好度 85/100
clerk/javascript#10708 ·
維護者通常 1 天內回覆
-
Built-in reverification dialog lacks an accessible name (aria-dialog-name)可能已有人在做 關聯的 PR 仍在進行中或已合併。 未關閉
難度 2/5 1-3 小時 新手友好度 75/100
clerk/javascript#10548 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 84/100
clerk/javascript#10547 ·
維護者通常 1 天內回覆
-
<SignIn />: first "Use email" click switches back to phone when `initialValues.phoneNumber` is set可能已有人在做 @twicestruck 於 20 天前認領。 未關閉
難度 2/5 1-3 小時 新手友好度 74/100
clerk/javascript#10487 ·
維護者通常 1 天內回覆
-
useLoadedIsomorphicClerk misses "ready" when a ClerkProvider remounts after clerk-js has loaded — <ClerkLoading> never resolves可能重新可做 關聯的 PR 已關閉且未合併。 未關閉
難度 2/5 1-3 小時 新手友好度 82/100
clerk/javascript#10462 ·
維護者通常 1 天內回覆
相似的 Issue
-
難度 2/5 1-3 小時 新手友好度 78/100
oxc-project/tsrs#1010 ·
維護者通常 1 天內回覆
-
area:infra area:storage bug
難度 2/5 1-3 小時 新手友好度 76/100
THU-MAIC/OpenMAIC#2311 · 1 則留言 ·
維護者通常 1 天內回覆
-
docs documentation need-triage SaaS
難度 2/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆
-
enhancement from-app needs-triage
難度 2/5 1-3 小時 新手友好度 68/100
nightly-labs/openbot#10973 ·
維護者通常 1 天內回覆
-
status/need-triage
難度 2/5 1-3 小時 新手友好度 76/100
google-gemini/gemini-cli#30328 · 1 則留言 ·
維護者通常 1 天內回覆