fix(react-query): add experimental_prefetchInRender support to useQueries

[isaackaara]

Problem

experimental_prefetchInRender works with useQuery but not with useQueries. When using React.use(promise) with useQueries, the component never finishes loading because the promise never resolves.

const query = queryOptions({
  queryKey: ['foo'],
  queryFn: async () => [],
  experimental_prefetchInRender: true,
});

// ✅ Works with useQuery
const { promise } = useQuery(query);
React.use(promise);

// ❌ Never finishes loading with useQueries
const [{ promise }] = useQueries({ queries: [query] });
React.use(promise);

Root Cause

useBaseQuery implements experimental_prefetchInRender by detecting when a query will fetch and either:

1. Triggering an optimistic fetch for new cache entries, or
2. Subscribing to the existing cache promise

When the promise resolves, it calls observer.updateResult() which finalizes the currentThenable.

useQueries was missing this logic entirely — the experimental_prefetchInRender option was ignored.

Fix

Added the same prefetch-in-render logic to useQueries, iterating over each query's result and options to handle the experimental_prefetchInRender flag individually. For each query that will fetch and has the option enabled:

• New cache entries trigger fetchOptimistic() immediately
• Existing cache entries subscribe to the query's cache promise
• On promise resolution, observer.updateResult() is called to finalize the thenable

Closes #9988

Summary by CodeRabbit

• New Features

  • Added client-side support for experimental prefetch-on-render optimization, improving data loading and responsiveness when rendering queries.

• Chores

  • Added release changeset documenting the patch and the new prefetch-on-render behavior.

[changeset-bot]

🦋 Changeset detected

Latest commit: 58ccf61

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@tanstack/react-query	Patch
@tanstack/react-query-devtools	Patch
@tanstack/react-query-next-experimental	Patch
@tanstack/react-query-persist-client	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cd30ee56-8255-4409-9bcb-a54d6c44cbbc

📥 Commits

Reviewing files that changed from the base of the PR and between 36db743 and 58ccf61.

📒 Files selected for processing (1)

• .changeset/fix-use-queries-prefetch-in-render.md

---

📝 Walkthrough

Walkthrough

Adds client-side handling for experimental_prefetchInRender in useQueries: for optimistic results it locates the QueryObserver/Query from cache, triggers an optimistic fetch or subscribes to an existing cache promise (client-only), and updates observer results when the promise settles.

Changes

Cohort / File(s)	Summary
useQueries prefetch logic packages/react-query/src/useQueries.ts	Adds client-only experimental_prefetchInRender handling: for optimistic query results it retrieves the QueryObserver/Query from cache, calls fetchOptimistic or subscribes to cache promise, attaches noop catch, and updates observer results. Adds imports: isServer, willFetch.
Changeset .changeset/fix-use-queries-prefetch-in-render.md	Adds a patch changeset documenting experimental_prefetchInRender support for useQueries.

Sequence Diagram(s)

sequenceDiagram
    participant Render as Client Render
    participant Cache as Query Cache
    participant Observer as QueryObserver
    participant Query as Query (core)

    Render->>Cache: find Query / QueryObserver for queryKey
    alt query has no dataUpdateCount
        Render->>Query: fetchOptimistic() (start fetch)
        Query-->>Render: returns promise
    else existing cache promise
        Render->>Cache: subscribe to cache promise
        Cache-->>Render: returns existing promise
    end
    Render->>Render: attach .catch(noop).finally(update observer result)
    Render->>Observer: updateObserverResult() with new data

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• #10188 — touches useQueries suspense/prefetch logic and willFetch usage; closely related to reintroducing client-side prefetch branches.
• #10082 — removes a willFetch branch/import in useQueries; directly related/conflicting with added willFetch usage.
• #9576 — modifies experimental_prefetchInRender promise semantics and thenable behavior; intersects with optimistic prefetch handling.

Suggested reviewers

• TkDodo

Poem

🐰 In render I sniffed a pending quest,
I nudged a query, gave it my best.
An optimistic hop, a promise unfurled,
Now useQueries greets a prefetching world.
✨🫶

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: adding experimental_prefetchInRender support to useQueries.
Description check	✅ Passed	The description covers the problem, root cause, and fix clearly, though the checklist section is not filled out by the author.
Linked Issues check	✅ Passed	The PR implements all coding requirements from issue #9988: adding prefetch-in-render logic to useQueries with per-query handling, optimistic fetches, cache promise subscription, and observer updates.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing experimental_prefetchInRender support in useQueries as required by the linked issue.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}