`@clerk/nextjs` with `cacheComponents`: after a root param change (`/en` → `/sk`), `Clerk.navigate()` within `/sk` never resolves

未關閉
#10,539 0 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

維護者通常 1 天內回覆

@Joozty 已經在處理了。

開始於 2026年10月30日。

  • #10540 來自 @Joozty —— 未關閉

評估

難度
4/5
預估耗時
3-5 天
新手友好度
35/100
Issue 類型
缺陷
描述清晰度
描述清楚
活躍度
停滯

研究方向

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 內容生成。

描述

needs-triage
Preliminary Checks
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:

  1. Clone the reproduction and run pnpm install.
  2. Copy .env.example to .env.local. Set the publishable key of your own development instance there.
  3. Run pnpm dev and open http://localhost:3000/en.
  4. Click Test Clerk.navigate(). It shows resolved.
  5. Click the /sk link. 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 build and pnpm start give the same result.
  • partialPrefetching: false gives the same result.
  • Without cacheComponents, the promise resolves. (Remove both cacheComponents and partialPrefetching from next.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:

  1. In the browser, Next.js puts the value of [lang] in the React key of the segment. So /en and /sk are two different React trees. With cacheComponents, Next.js doesn't unmount the /en tree. It hides the tree in <Activity>. Now two ClerkProviders are mounted.
  2. useInternalNavFun (packages/nextjs/src/app-router/client/useInternalNavFun.ts) saves its navigation function in window.__clerk_internal_navigations[name].fun during render.
  3. The hidden tree still renders. useRouter() from next/navigation reads LayoutRouterContext, and Next.js gives this context a new value on every navigation. So after each navigation, the hidden ClerkProvider renders after the visible one. Its function replaces the visible tree's function.
  4. The hidden tree's function starts the navigation with the hidden tree's startTransition. The promise resolves only when an effect runs: the isPending effect of the hidden tree, or the effect that runs when a ClerkProvider is 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.
  5. Later calls with the same URL don't navigate at all, because pendingDestination is 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, so setActive() 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, because afterSignOutUrl (/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 first afterSignOutUrl, 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: afterSignOutUrl keeps its first value.
  • #2899 and #3480 moved this navigation function to window and set it during render. This design expects only one mounted ClerkProvider.
  • #7989 removed usePathname from this hook for cacheComponents. Since then, only isPending or a ClerkProvider that 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 cacheComponents sign-out tests, and #8071 skipped them because toBeSignedOut() timed out. They are still skipped on main. That test app has one root layout without params, so the cause may be different.
  • #9987 also makes setActive() and signOut() hang, but the cause is different: there, onBeforeSetActive never finishes. Its fix, #10088, doesn't change useInternalNavFun, 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 cacheComponents keeping 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 ThemeProvider of 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

環境準備

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

clerk/javascript 的其他 Issue

查看 clerk/javascript 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。