fix(solid-query): don't re-trigger Suspense on background refetches #11230
main fromrefs/pull/11230/head·opened Summary#
Background refetches (and mounts with cached data) no longer flip enclosing <Suspense> boundaries. This fixes CSS animations restarting, and focus/scroll/iframe state resetting, on every query update.
Fixes #9955
Related: #9883, and the downstream report TanStack/router#8000 (solid-router wraps every route match in <Suspense>, so route components can't escape a boundary — which made this present as a router bug).
Root cause#
useBaseQuery's client subscriber calls the resource's refetch() on every observer notification, and the fetcher always returned a Promise — even when it resolved within the same tick (!isLoading → resolve() called synchronously in the executor). A native Promise's .then fires a microtask later, so the resource spent at least one microtask in a pending/refreshing state with pr set.
Any query.data read that ever registered with a SuspenseContext while pr was set leaves behind a tracking computed that re-runs on every trigger() and increments the boundary again (the .latest fast path can't prevent this: on mount with cached data, resolved is still false during that first microtask, so the initial read registers anyway — and structural sharing keeps data referentially stable, so the reading memo never re-runs and never disposes the computed).
The boundary flips to fallback and back within one microtask. That's never painted, but Suspense detaches and re-inserts the children's DOM — and reconnecting an element restarts its CSS animations. Verified in the router#8000 repro with a MutationObserver: the exact same DOM node is removed and re-inserted 1 ms apart precisely when a background refetch settles.
The existing mitigations in #10053 / #10592 gate on isFetching === false, so the stale-mount case (refetch already in flight at mount) still flips.
Fix#
When the observer result has data and is not in an initial loading state, the fetcher returns the result synchronously (a non-thenable). Solid's load() completes non-Promise results immediately without ever setting a pending promise, so Suspense is only triggered by genuine initial loads. Two exceptions preserve existing semantics:
- If a previous fetcher promise is still pending (
resolverset — an in-flight initial load, where the boundary is already suspended and possibly inside a transition), completion goes through the Promise path so Suspense/Transition bookkeeping resolves correctly. - No-data results (e.g. disabled queries) keep the previous Promise behavior; there is no rendered content to protect and existing tests rely on the fallback window.
Behavior change#
should refetch when re-mounting previously asserted that the Suspense fallback shows when re-mounting a component whose query has cached data. That expectation codified the reported bug; the test now expects cached data to render immediately while the mount refetch runs in the background (matching React useSuspenseQuery semantics). The refetch itself still happens and is still asserted.
Validation#
- 2 new regression tests: mounting with cached data during a background refetch, and invalidation-triggered refetch of a mounted query — both assert the fallback never renders and DOM node identity is preserved
- Full solid-query runtime suite: 322 passed (baseline on main: 320), no new failures; transition test passes
- End-to-end: built package swapped into the router#8000 repro — the same-node detach/re-insert at refetch completion is gone and the animation plays once
🤖 Generated with Claude Code
Summary by CodeRabbit#
- Bug Fixes
- Improved Suspense behavior when displaying cached data.
- Background refetches and query invalidations no longer unnecessarily re-trigger Suspense or detach and remount content.
- Initial loads without available data continue to suspend as expected.
- Improved error handling and hydration behavior across server and client rendering.
- 1
View your CI Pipeline Execution ↗ for commit cb08a8fea3e99ec3694dc65c4277ae669815feb1
Command Status Duration Result nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded 3m 24s View ↗ nx run-many --target=build --exclude=examples/*...✅ Succeeded 7s View ↗
☁️ Nx Cloud last updated this comment at
2026-08-18 22:56:30UTCMore templates
- @tanstack/query-example-angular-auto-refetching
- @tanstack/query-example-angular-basic
- @tanstack/query-example-angular-basic-persister
- @tanstack/query-example-angular-devtools-panel
- @tanstack/query-example-angular-infinite-query-with-max-pages
- @tanstack/query-example-angular-optimistic-updates
- @tanstack/query-example-angular-pagination
- @tanstack/query-example-angular-query-options-from-a-service
- @tanstack/query-example-angular-router
- @tanstack/query-example-angular-rxjs
- @tanstack/query-example-angular-simple
- @tanstack/query-example-preact-simple
- @tanstack/query-example-lit-basic
- @tanstack/query-example-lit-pagination
- @tanstack/query-example-lit-ssr
- @tanstack/query-example-react-algolia
- @tanstack/query-example-react-auto-refetching
- @tanstack/query-example-react-basic
- @tanstack/query-example-react-basic-graphql-request
- @tanstack/query-example-chat
- @tanstack/query-example-react-default-query-function
- @tanstack/query-example-react-devtools-panel
- @tanstack/query-example-eslint-legacy
- @tanstack/query-example-eslint-plugin-demo
- @tanstack/query-example-react-infinite-query-with-max-pages
- @tanstack/query-example-react-load-more-infinite-scroll
- @tanstack/query-example-react-nextjs
- @tanstack/query-example-react-nextjs-app-optimistic-updates
- @tanstack/query-example-react-nextjs-app-prefetching
- @tanstack/query-example-nextjs-suspense-streaming
- @tanstack/query-example-react-offline
- @tanstack/query-example-react-pagination
- @tanstack/query-example-react-playground
- @tanstack/query-example-react-prefetching
- @tanstack/query-example-react-react-native
- @tanstack/query-example-react-router
- @tanstack/query-example-react-rick-morty
- @tanstack/query-example-react-shadow-dom
- @tanstack/query-example-react-simple
- @tanstack/query-example-react-star-wars
- @tanstack/query-example-react-suspense
- @tanstack/query-example-solid-astro
- @tanstack/query-example-solid-basic
- @tanstack/query-example-solid-basic-graphql-request
- @tanstack/query-example-solid-default-query-function
- @tanstack/query-example-solid-offline
- @tanstack/query-example-solid-simple
- @tanstack/query-example-solid-start-streaming
- @tanstack/query-example-svelte-auto-refetching
- @tanstack/query-example-svelte-basic
- @tanstack/query-example-svelte-load-more-infinite-scroll
- @tanstack/query-example-svelte-optimistic-updates
- @tanstack/query-example-svelte-playground
- @tanstack/query-example-svelte-simple
- @tanstack/query-example-svelte-ssr
- @tanstack/query-example-svelte-star-wars
- @tanstack/query-example-vue-2.6-basic
- @tanstack/query-example-vue-2.7-basic
- @tanstack/query-example-vue-basic
- @tanstack/query-example-vue-dependent-queries
- @tanstack/query-example-vue-nuxt3
- @tanstack/query-example-vue-persister
- @tanstack/query-example-vue-simple
@tanstack/angular-query-experimental
npm i https://pkg.pr.new/@tanstack/angular-query-experimental@11230@tanstack/eslint-plugin-query
npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@11230@tanstack/lit-query
npm i https://pkg.pr.new/@tanstack/lit-query@11230@tanstack/preact-query
npm i https://pkg.pr.new/@tanstack/preact-query@11230@tanstack/preact-query-devtools
npm i https://pkg.pr.new/@tanstack/preact-query-devtools@11230@tanstack/preact-query-persist-client
npm i https://pkg.pr.new/@tanstack/preact-query-persist-client@11230@tanstack/query-async-storage-persister
npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@11230@tanstack/query-broadcast-client-experimental
npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@11230@tanstack/query-core
npm i https://pkg.pr.new/@tanstack/query-core@11230@tanstack/query-devtools
npm i https://pkg.pr.new/@tanstack/query-devtools@11230@tanstack/query-persist-client-core
npm i https://pkg.pr.new/@tanstack/query-persist-client-core@11230@tanstack/query-sync-storage-persister
npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@11230@tanstack/react-query
npm i https://pkg.pr.new/@tanstack/react-query@11230@tanstack/react-query-devtools
npm i https://pkg.pr.new/@tanstack/react-query-devtools@11230@tanstack/react-query-next-experimental
npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@11230@tanstack/react-query-persist-client
npm i https://pkg.pr.new/@tanstack/react-query-persist-client@11230@tanstack/solid-query
npm i https://pkg.pr.new/@tanstack/solid-query@11230@tanstack/solid-query-devtools
npm i https://pkg.pr.new/@tanstack/solid-query-devtools@11230@tanstack/solid-query-persist-client
npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@11230@tanstack/svelte-query
npm i https://pkg.pr.new/@tanstack/svelte-query@11230@tanstack/svelte-query-devtools
npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@11230@tanstack/svelte-query-persist-client
npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@11230@tanstack/vue-query
npm i https://pkg.pr.new/@tanstack/vue-query@11230@tanstack/vue-query-devtools
npm i https://pkg.pr.new/@tanstack/vue-query-devtools@11230commit:
cb08a8fbrenelz(GitHub profile, opens in a new tab) linked this to fix #9955
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID:
64b178e6-1ab7-4195-a137-6c4c49d19adb📥 Commits
Reviewing files that changed from the base of the PR and between b8e35598ef24855a2792414faea5721d833fa61e and cb08a8fea3e99ec3694dc65c4277ae669815feb1.
📒 Files selected for processing (3)
.changeset/solid-suspense-background-refetch.mdpackages/solid-query/src/__tests__/suspense.test.tsxpackages/solid-query/src/useBaseQuery.tsIncluded review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.
📝 Walkthrough
Walkthrough#
The Solid Query resource fetcher now resolves available client data synchronously when no fetch is pending. Server hydration and error handling remain promise-based. Suspense tests cover cached mounts, remounts, and invalidation refetches.
Changes#
Solid Suspense resolution
packages/solid-query/src/useBaseQuery.tspackages/solid-query/src/__tests__/suspense.test.tsx,.changeset/solid-suspense-background-refetch.mdEstimated code review effort: 3 (Moderate) | ~20 minutes
Merge Risk: ⚪ Minimal · up to
cb08aThe change keeps cached data rendered during background refetches so Suspense boundaries no longer reset UI state; no actionable merge-blocking risk remains beyond normal checks and review.
Possibly related PRs
useBaseQuery.tsand Solid Suspense behavior.Suggested labels:
package: solid-querySuggested reviewers:
tkdodo🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
#9955] by returning cached query results synchronously and preventing unnecessary Suspense triggering after prior data loading.✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share