add ability to warn when suspense queries aren't prefetched

[juliusmarminge]

When using the promise-rsc-hydration thingy we aim to prefetch all queries in the RSCs and just consume the streamed promises in our components.

This can be a bit fragile since forgetting to prefetch may not be obvious to find. This PR adds a new option that, when enabled, will log at warning level when useSuspenseQuery is called on a new query that's not already observed.

as with all options, this can be set globally when constructing the QueryClient and overridden locally cause you may have queries

Questions

• naming? idk, just went with the first thing that came to mind. as a matter of fact it's not even bound to being on the server as you may wanna use this with a usePrefetchQuery -> useSuspenseQuery pattern in a SPA as well
• given @TkDodo's recent talk, this should probably also accept a callback that gets the query(?) and not just a static boolean flag
• warning log might be too specific, would it be better for this to be a function and allow the developer to control what should happen? Perhaps they want to log more/less info about the query to help track down the query that's missing a prefetch

[nx-cloud[bot]]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 0e5b86c91c21d3eda32cecb86c700dd6b7dae18a. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

🟥 Failed Commands
nx affected --targets=test:sherif,test:knip,test:eslint,test:lib,test:types,test:build,build --parallel=3

✅ Successfully ran 1 target

- [`nx run-many --target=build --exclude=examples/** --exclude=integrations/**`](https://cloud.nx.app/runs/tj7vD1nVh4?utm_source=pull-request&utm_medium=comment)

---

Sent with 💌 from NxCloud.

[pkg-pr-new[bot]]

Open in Stackblitz

More templates

- [@tanstack/query-example-angular-basic](https://pkg.pr.new/template/bb6b0514-6b5b-4162-ac95-d448964703ff) - [@tanstack/query-example-angular-devtools-panel](https://pkg.pr.new/template/2063d35e-0921-46a1-a977-c45f9d32cb84) - [@tanstack/query-example-angular-infinite-query-with-max-pages](https://pkg.pr.new/template/e865006e-617c-4c41-80e7-199bf45895fc) - [@tanstack/query-example-angular-pagination](https://pkg.pr.new/template/fd351743-70d2-4fc0-85cb-b67816135563) - [@tanstack/query-example-angular-query-options-from-a-service](https://pkg.pr.new/template/555b646b-ddde-4c59-8ed3-bf1bbe0ba7ec) - [@tanstack/query-example-angular-router](https://pkg.pr.new/template/081016be-8c8a-4403-8e88-aeaddac2c221) - [@tanstack/query-example-angular-rxjs](https://pkg.pr.new/template/f869ceeb-994e-4c2b-ad50-ac477bdad1a4) - [@tanstack/query-example-angular-simple](https://pkg.pr.new/template/78d86ec1-e18f-463d-aad8-9de4fccdfd02) - [@tanstack/query-example-solid-astro](https://pkg.pr.new/template/9963d1fd-3f3e-4d65-8ef5-dcad67e203de) - [@tanstack/query-example-solid-basic](https://pkg.pr.new/template/bc36803d-50b4-4647-bfdd-529c229769a9) - [@tanstack/query-example-solid-basic-graphql-request](https://pkg.pr.new/template/369c6e3e-4ddc-4e7d-a420-fafab7e4c90e) - [@tanstack/query-example-solid-default-query-function](https://pkg.pr.new/template/654245b6-3506-4464-9a03-05730006a108) - [@tanstack/query-example-solid-simple](https://pkg.pr.new/template/cd6ba4cb-96a9-47a7-98ad-eebdf9958968) - [@tanstack/query-example-solid-start-streaming](https://pkg.pr.new/template/d554c4de-e150-4970-be23-75f7eae46064) - [@tanstack/query-example-react-algolia](https://pkg.pr.new/template/bfc3d3f1-cbe6-4ece-acf1-100f42be6a87) - [@tanstack/query-example-react-auto-refetching](https://pkg.pr.new/template/4f3276fd-40c7-4a9d-a333-d9d6625fdb81) - [@tanstack/query-example-react-basic](https://pkg.pr.new/template/fc92368c-4168-4460-9941-960eb1350dff) - [@tanstack/query-example-react-basic-graphql-request](https://pkg.pr.new/template/a13859d1-4447-4c87-8977-cbc15d3025d6) - [@tanstack/query-example-react-default-query-function](https://pkg.pr.new/template/a236262b-7a4f-448c-82d1-a2d0d6b792a8) - [@tanstack/query-example-react-devtools-panel](https://pkg.pr.new/template/b1f94d3c-27b1-4da7-bc1e-559c947e9dbe) - [@tanstack/query-example-react-infinite-query-with-max-pages](https://pkg.pr.new/template/95f7f4eb-1916-4e0a-a333-231759f060f6) - [@tanstack/query-example-react-load-more-infinite-scroll](https://pkg.pr.new/template/f9b259b3-fc61-4b17-a8d1-732983650542) - [@tanstack/query-example-react-nextjs](https://pkg.pr.new/template/17605e4a-edd7-4c87-af03-4e9fc487ccd1) - [@tanstack/query-example-react-nextjs-app-prefetching](https://pkg.pr.new/template/6629a084-e9a4-4f71-b402-8784a0dfd133) - [@tanstack/query-example-nextjs-suspense-streaming](https://pkg.pr.new/template/d1d105ea-d0f9-4e0c-b660-7321ea4d6768) - [@tanstack/query-example-react-offline](https://pkg.pr.new/template/c78fe117-721d-4b0d-9e20-b8e3dc789619) - [@tanstack/query-example-react-optimistic-updates-cache](https://pkg.pr.new/template/a2f6bdd7-9ed6-455e-ac53-ff5f0486ca9d) - [@tanstack/query-example-react-optimistic-updates-ui](https://pkg.pr.new/template/954fe843-9841-4a02-85fb-29b929643c14) - [@tanstack/query-example-react-pagination](https://pkg.pr.new/template/d31215ab-7ce1-4fac-8d1d-9b78840f01ca) - [@tanstack/query-example-react-playground](https://pkg.pr.new/template/26a8f668-2591-45c5-9a44-9332b54e8ddb) - [@tanstack/query-example-react-prefetching](https://pkg.pr.new/template/48eead55-aba0-4887-a082-ef6da1c540c8) - [@tanstack/query-example-react-react-native](https://pkg.pr.new/template/d6d6ba3b-72a8-41c3-b990-57600b873208) - [@tanstack/query-example-react-router](https://pkg.pr.new/template/ef5b4896-700b-4664-9faa-95c335338220) - [@tanstack/query-example-react-rick-morty](https://pkg.pr.new/template/6128f633-b4c2-4a06-ad84-912946eab410) - [@tanstack/query-example-react-shadow-dom](https://pkg.pr.new/template/ae64aa0a-409c-44dd-a114-7b48b2f67d0c) - [@tanstack/query-example-react-simple](https://pkg.pr.new/template/a154f3b4-daa6-4c99-9857-0ddb69f92dbf) - [@tanstack/query-example-react-star-wars](https://pkg.pr.new/template/d04382ae-2417-4f4e-8c94-547bcee9cd3d) - [@tanstack/query-example-react-suspense](https://pkg.pr.new/template/bfe9533c-60c9-4b7d-898f-ed5bb34a4034) - [@tanstack/query-example-vue-2.6-basic](https://pkg.pr.new/template/cc186e56-6876-4773-92ad-9b692b9b17b6) - [@tanstack/query-example-vue-2.7-basic](https://pkg.pr.new/template/34e7e29b-a520-48b1-a313-257a9c43da07) - [@tanstack/query-example-vue-basic](https://pkg.pr.new/template/63a0a0e5-583b-4418-9bbe-983e94cbc5bd) - [@tanstack/query-example-vue-dependent-queries](https://pkg.pr.new/template/3dd8ba4e-555f-49cc-a788-58f17d9c5214) - [@tanstack/query-example-vue-nuxt3](https://pkg.pr.new/template/1c6f39ea-b676-4657-ad07-847a63e14d61) - [@tanstack/query-example-vue-persister](https://pkg.pr.new/template/6d6ecdd6-0648-4582-8fa6-02e52d98b14e) - [@tanstack/query-example-vue-simple](https://pkg.pr.new/template/1000dd5e-78ce-44f0-a8b0-c5189cb6cbfa) - [@tanstack/query-example-svelte-auto-refetching](https://pkg.pr.new/template/9c2d09bf-fd0c-41ed-8fde-2fb1ca768b61) - [@tanstack/query-example-svelte-basic](https://pkg.pr.new/template/596f8841-5ddc-41f4-b140-09f94f292b3e) - [@tanstack/query-example-svelte-load-more-infinite-scroll](https://pkg.pr.new/template/3c4d6965-247b-47bc-9ff2-33c173b4f786) - [@tanstack/query-example-svelte-optimistic-updates](https://pkg.pr.new/template/8b45591d-b8c8-42e2-a037-f513dfd5d988) - [@tanstack/query-example-svelte-playground](https://pkg.pr.new/template/cacd69ce-57f2-4284-b3f3-890458baf84d) - [@tanstack/query-example-svelte-ssr](https://pkg.pr.new/template/44120223-6fa9-41cc-80f0-63b75bad1e6c) - [@tanstack/query-example-svelte-simple](https://pkg.pr.new/template/05a43d8d-0ed0-41a6-83b7-afec53274027) - [@tanstack/query-example-svelte-star-wars](https://pkg.pr.new/template/4692d565-54eb-4219-99a3-b3fd832bef32)

@tanstack/angular-query-devtools-experimental

``` pnpm add https://pkg.pr.new/@tanstack/angular-query-devtools-experimental@8309 ```

@tanstack/angular-query-experimental

``` pnpm add https://pkg.pr.new/@tanstack/angular-query-experimental@8309 ```

@tanstack/query-async-storage-persister

``` pnpm add https://pkg.pr.new/@tanstack/query-async-storage-persister@8309 ```

@tanstack/eslint-plugin-query

``` pnpm add https://pkg.pr.new/@tanstack/eslint-plugin-query@8309 ```

@tanstack/query-broadcast-client-experimental

``` pnpm add https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@8309 ```

@tanstack/query-core

``` pnpm add https://pkg.pr.new/@tanstack/query-core@8309 ```

@tanstack/query-devtools

``` pnpm add https://pkg.pr.new/@tanstack/query-devtools@8309 ```

@tanstack/query-persist-client-core

``` pnpm add https://pkg.pr.new/@tanstack/query-persist-client-core@8309 ```

@tanstack/query-sync-storage-persister

``` pnpm add https://pkg.pr.new/@tanstack/query-sync-storage-persister@8309 ```

@tanstack/react-query

``` pnpm add https://pkg.pr.new/@tanstack/react-query@8309 ```

@tanstack/react-query-devtools

``` pnpm add https://pkg.pr.new/@tanstack/react-query-devtools@8309 ```

@tanstack/react-query-next-experimental

``` pnpm add https://pkg.pr.new/@tanstack/react-query-next-experimental@8309 ```

@tanstack/react-query-persist-client

``` pnpm add https://pkg.pr.new/@tanstack/react-query-persist-client@8309 ```

@tanstack/solid-query

``` pnpm add https://pkg.pr.new/@tanstack/solid-query@8309 ```

@tanstack/solid-query-devtools

``` pnpm add https://pkg.pr.new/@tanstack/solid-query-devtools@8309 ```

@tanstack/solid-query-persist-client

``` pnpm add https://pkg.pr.new/@tanstack/solid-query-persist-client@8309 ```

@tanstack/svelte-query

``` pnpm add https://pkg.pr.new/@tanstack/svelte-query@8309 ```

@tanstack/svelte-query-devtools

``` pnpm add https://pkg.pr.new/@tanstack/svelte-query-devtools@8309 ```

@tanstack/svelte-query-persist-client

``` pnpm add https://pkg.pr.new/@tanstack/svelte-query-persist-client@8309 ```

@tanstack/vue-query

``` pnpm add https://pkg.pr.new/@tanstack/vue-query@8309 ```

@tanstack/vue-query-devtools

``` pnpm add https://pkg.pr.new/@tanstack/vue-query-devtools@8309 ```

commit: 0e5b86c

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 50.00000% with 1 line in your changes missing coverage. Please review.

Project coverage is 62.67%. Comparing base (4a2e838) to head (8143f1d). Report is 6 commits behind head on main.

Additional details and impacted files

[](https://app.codecov.io/gh/TanStack/query/pull/8309?src=pr&el=tree&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) ```diff @@ Coverage Diff @@ ## main #8309 +/- ## =========================================== + Coverage 45.96% 62.67% +16.71% =========================================== Files 199 135 -64 Lines 7501 4799 -2702 Branches 1717 1348 -369 =========================================== - Hits 3448 3008 -440 + Misses 3676 1549 -2127 + Partials 377 242 -135 ``` | [Components](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=components&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | Coverage Δ | | |---|---|---| | [@tanstack/angular-query-devtools-experimental](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/angular-query-experimental](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `88.21% <100.00%> (-0.05%)` | :arrow_down: | | [@tanstack/eslint-plugin-query](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/query-async-storage-persister](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `43.85% <100.00%> (ø)` | | | [@tanstack/query-broadcast-client-experimental](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/query-codemods](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/query-core](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `93.69% <100.00%> (-0.01%)` | :arrow_down: | | [@tanstack/query-devtools](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `4.78% <ø> (ø)` | | | [@tanstack/query-persist-client-core](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `57.73% <ø> (ø)` | | | [@tanstack/query-sync-storage-persister](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `84.61% <0.00%> (+2.11%)` | :arrow_up: | | [@tanstack/react-query](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `95.23% <50.00%> (-0.31%)` | :arrow_down: | | [@tanstack/react-query-devtools](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `10.00% <ø> (ø)` | | | [@tanstack/react-query-next-experimental](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/react-query-persist-client](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `100.00% <ø> (ø)` | | | [@tanstack/solid-query](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `78.20% <ø> (ø)` | | | [@tanstack/solid-query-devtools](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/solid-query-persist-client](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `100.00% <ø> (ø)` | | | [@tanstack/svelte-query](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `87.33% <0.00%> (ø)` | | | [@tanstack/svelte-query-devtools](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | | | [@tanstack/svelte-query-persist-client](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `100.00% <ø> (ø)` | | | [@tanstack/vue-query](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `71.45% <ø> (ø)` | | | [@tanstack/vue-query-devtools](https://app.codecov.io/gh/TanStack/query/pull/8309/components?src=pr&el=component&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=TanStack) | `∅ <ø> (∅)` | |

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests
• JS Bundle Analysis - Avoid shipping oversized bundles

[TkDodo]

I had as similar idea recently, but wanted to actually create some kind of StrictMode component that would only do this in dev-mode, but there, trigger a hard failure. Please have a look at the RFC:

• https://github.com/TanStack/query/discussions/8064

[juliusmarminge]

Yea that's a much more thought out idea compared to this PR which I put together in 5 minutes after a meeting :)

[TkDodo]

Yea that's a much more thought out idea compared to this PR which I put together in 5 minutes after a meeting :)

😂 . Would you like to give implementing the first part of it a try? Specifically, the under-prefetching part, as it overlaps with what you were trying to do here:

Whenever useSuspenseQuery would suspend the component with a new promise, it would log an error. This will alert developers that they are using a suspense query, but haven’t prefetched it. When the component renders, it should merely pick up a promise that is already in the cache. This would address the under-prefetching issue.

Bonus points if it would also work with the use(promise) experimental feature 😁