Hydration error thrown when using `PersistQueryClientProvider` and `Suspense`
維護者通常 1 天內回覆
還沒有人認領這個 Issue。
評估
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 新手友好度
- 35/100
- Issue 類型
- 缺陷
- 描述清晰度
- 基本清楚
- 活躍度
- 停滯
- 技術堆疊
- next.js, react, typescript
- 領域
- frontend
研究方向
先在本機執行連結的最小重現,然後比較載入與不載入 loading.tsx 時的行為,以及在 layout.tsx 中將 SomeData 包在 Suspense 中與不包裝時的行為。追蹤 PersistQueryClientProvider、createAsyncStoragePersister 和 useIsRestoring,以判斷還原期間預期的 pending 狀態;當快取資料在此重現中不再造成 hydration mismatch 時,即表示完成。
由索引模型根據 Issue 內容生成。
描述
Describe the bug
My real use-case:
- A modern Next.js app with authentication
- The authentication is completely offloaded to the browser
- The server does not have an auth token (a JWT, but knows if the user is potentially logged in if a refresh token is present)
- When logged in, the server returns loaders for the UI parts that are user specific
- The browser replaces them with actual data
- The browser caches data in
localStorageusingPersistQueryClientProviderandcreateAsyncStoragePersister
However, the example attached isn't that complex, it's a minimal example which reproduces the issue.
For the case above, the browser might have instant access to cached authenticated data. For instance, let's say we want to print the user's email address. The user has logged in earlier and this data is cached in localStorage, and as mentioned above, the server doesn't have this data. This is what happens:
- Both the server and the client call the same
useQuery. - Server: Since this data is not prefetched, the
statusis alwayspendingin the server, and a loader is returned - Client: The client hydrates, but it instantly has access to the cached
userand prints the email address
There is a mismatch here since the server rendered loading, while the client the email address. This case seems to be handled well when a component is not in a Suspense, but when it is, the last step will throw hydration errors (whether that's a loading.tsx or just a manual <Suspense>).
I have added some logs, and here is what I get:
Component not in Suspense:
not in suspense {status: 'pending', data: undefined, isRestoring: true}
not in suspense {status: 'success', data: {…}, isRestoring: false}
Component in Suspense:
in suspense {status: 'success', data: {…}, isRestoring: true}
in suspense {status: 'success', data: {…}, isRestoring: false}
When the component within a Suspense is rendering for the first time, the status is success, which renders data differently from the server, which I believe is the cause of the hydration error.
From the repo, here is part of the code that handles the loading UI:
const { data, status } = useSomeData();
if (status === "pending") {
return <main>loading</main>;
}
The workaround is:
const { data, status } = useSomeData();
const isRestoring = useIsRestoring();
if (status === "pending" || isRestoring) {
return <main>loading</main>;
}
That works, and does not throw hydration errors. But I feel that is bad DX, and I would prefer not to have to do that for every query call.
Your minimal, reproducible example
https://github.com/ali-idrizi/react-query-suspense-hydration-error
Steps to reproduce
Unfortunately it's a bit difficult to test this on CodeSandbox, as it doesn't seems to throw any hydration errors for some reason. Even rendering a simple {typeof window === 'undefined' ? 'x' : 'y'} does not throw an error for me. I have attached a repo instead, and you might have to run this locally, but there is also a video recording below.
To see the error, you will have to load the page once, so the data gets cached in the browser, afterwards the issue occurs on every subsequent reload.
You can try:
- Remove the
loading.tsxfile and notice no hydration errors thrown - Wrap the
SomeDatacomponent inlayout.tsxwith aSuspenseand notice the hydration error count increase
Expected behavior
Perhaps keep status as pending while isRestoring === true, similar to when a component is not within a Suspense?
How often does this bug happen?
Every time
Screenshots or Videos
https://github.com/TanStack/query/assets/20397725/4581ed80-60b1-4b36-b2b3-d16136f25bc1
Platform
- Windows 10 (WSL)
- Chrome 119
Tanstack Query adapter
react-query
TanStack Query version
5.12.2
TypeScript version
5.2.2
Additional context
No response
- 主要語言
- TypeScript
- 星號
- 50.6k
- 分支
- 4.2k
- 平均合併
- 9 小時 50 分鐘
- 30 天內合併 PR
- 310
環境準備
- 沒有 Dockerfile 或 Docker Compose 檔案
- 有 Pull Request 範本
- 閱讀貢獻指南
從這裡開始
- 先讀完整個 Issue,再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫,在一個分支上完成修改。
- 送出 Pull Request,並在描述裡引用這個 Issue 編號。
TanStack/query 的其他 Issue
-
難度 2/5 1-3 小時 新手友好度 78/100
TanStack/query#12466 · 1 則留言 ·
維護者通常 1 天內回覆
-
solid-query: STRICT_READ_UNTRACKED on Solid 2 — client()/options() read in component body (useMutation, useBaseQuery)可能重新可做 @LeonxLJX 於 77 天前認領,目前沒有進行中的 PR。 未關閉
難度 2/5 1-3 小時 新手友好度 84/100
TanStack/query#11358 · 2 則留言 · 1 個 reaction ·
維護者通常 1 天內回覆
-
select that throws for placeholderData brings back the selection of data removed by resetQueries可能已有人在做 關聯的 PR 仍在進行中或已合併。 未關閉
難度 3/5 1-2 天 新手友好度 56/100
維護者通常 1 天內回覆
-
Render loop since v5.105.2 when placeholderData, or its select result, is not referentially stable未關閉
難度 4/5 3-5 天 新手友好度 54/100
維護者通常 1 天內回覆
-
useQueries: stable combine returns a stale result when a query updates before setQueries runs可能已有人在做 @sakaintp 於 1 天前認領。 未關閉
難度 3/5 1-2 天 新手友好度 62/100
TanStack/query#12626 · 2 則留言 ·
維護者通常 1 天內回覆
相似的 Issue
-
難度 2/5 1-3 小時 新手友好度 78/100
fb55/htmlparser2#2579 ·
維護者通常 1 天內回覆
-
bug good first issue needs-review
難度 1/5 1-3 小時 新手友好度 83/100
維護者通常 1 天內回覆
-
documentation public
難度 1/5 1-3 小時 新手友好度 68/100
midnightntwrk/umbradb#65 ·
維護者通常 2 天內回覆
-
area/channels kind/bug priority/medium
難度 2/5 1-3 小時 新手友好度 78/100
nanocoai/nanoclaw#4501 · 1 則留言 ·
維護者通常 1 天內回覆
-
needs verification
難度 2/5 1-3 小時 新手友好度 74/100
維護者通常 13 天內回覆