@clerk/nextjs ≥ 7.9.24: module-level displayName mutation breaks App Router PPR resume ("Expected the resume to render <ClerkProvider> … <ReactClerkProvider>")
維護者通常 1 天內回覆
還沒有人認領這個 Issue。
評估
- 難度
- 3/5
- 預估耗時
- 1-2 天
- 新手友好度
- 64/100
- Issue 類型
- 缺陷
- 描述清晰度
- 描述清楚
- 活躍度
- 活躍
- 技術堆疊
- next.js, react, typescript
研究方向
Start with dist/esm/pages/ClerkProvider.js and trace how components.client.js and client-boundary/ClerkProvider.js load it alongside the App Router provider. Compare the 7.9.23 and 7.9.24 behavior around ReactClerkProvider.displayName, then run the linked reproduction’s build and request the page twice. Done means both requests resume the prerendered shell without the component-name mismatch or client-render fallback.
由索引模型根據 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/marcvive/clerk-ppr-resume-repro
Publishable key
pk_test_ZGVsaWNhdGUtYmx1ZWpheS05NDQwLmNsZXJrLmFjY291bnRzLmRldiQ
Description
Since 7.9.24, App Router apps using Partial Prerendering (cacheComponents: true) fail to resume their prerendered shell once a client component importing Show from @clerk/nextjs has been loaded on the server. The route falls back to client rendering on every request after that.
Steps to reproduce:
- Clone the reproduction,
cp .env.local.example .env.localand add the keys of a development instance. npm install && npm run build && npm start- Request the page twice:
curl -s http://localhost:3200/ > /dev/null(twice).
Expected behavior:
Both requests resume the prerendered shell without errors — as they do on @clerk/nextjs 7.9.23 (same repro, npm install @clerk/[email protected] --save-exact, rebuild).
Actual behavior:
The first request is fine. Every later request logs on the server:
Error: Expected the resume to render <ClerkProvider> in this slot but instead it rendered <ReactClerkProvider>. The tree doesn't match so React will fallback to client rendering.
and the browser logs minified React error #419. In our real app this fails our Playwright E2E suite; pinning 7.9.23 fixes it.
Root cause:
In 7.9.24, dist/esm/pages/ClerkProvider.js moved ReactClerkProvider.displayName = "ReactClerkProvider"; from inside the Pages Router ClerkProvider render function to module top level. ReactClerkProvider is InternalClerkProvider from @clerk/react/internal — the same component object the App Router provider (app-router/client/ClerkProvider.js) renders, and which @clerk/react names "ClerkProvider".
components.client.js → client-boundary/ClerkProvider.js imports ../pages/ClerkProvider unconditionally, and Show / ClerkProvider are re-exported from #components (= components.client.js). So the provider's name depends on load order: the build-time prerender records <ClerkProvider> in the postponed state; once a client component using Show is loaded on the server, every resume sees <ReactClerkProvider>. React's resume check compares component names (displayName || name), so it throws.
Hooks such as useAuth alone don't trigger it, because the package is "sideEffects": false and they never load components.client.js.
Suggested fix:
Don't mutate the shared component's displayName: move the assignment back inside the Pages Router render, or wrap the provider in a separately named local component.
Workaround: pin @clerk/[email protected].
Environment
System:
OS: Windows 11 10.0.26200
CPU: (8) x64 Intel(R) Core(TM) Ultra 7 258V
Memory: 10.15 GB / 31.57 GB
Binaries:
Node: 24.22.1 - C:\Program Files\nodejs\node.EXE
npm: 11.19.1 - C:\Program Files\nodejs\npm.CMD
Browsers:
Chrome: 156.0.8078.80
Edge: Chromium (152.0.4191.53)
Firefox: 159.0.1 - C:\Program Files\Mozilla Firefox\firefox.exe
npmPackages:
@clerk/nextjs: 7.9.25 => 7.9.25
next: 16.4.5 => 16.4.5
react: 19.3.1 => 19.3.1
react-dom: 19.3.1 => 19.3.1
- 主要語言
- 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 小時 新手友好度 67/100
ilan-pinto/roaring-lions#1552 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆
-
bug: [React Native/Android] KeepAliveService never starts when CAMERA is not granted (Android 14+)未關閉
難度 2/5 1-3 小時 新手友好度 78/100
cloudflare/realtimekit-ui#208 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 68/100
usebruno/bruno-vscode#235 ·
維護者通常 3 天內回覆
-
難度 2/5 1-3 小時 新手友好度 78/100
維護者通常 1 天內回覆