perf(react-query): Batch hydration notifications

[scttcper]

HydrationBoundary is the manual React SSR bridge used by Next.js and custom integrations to merge dehydrated server data into the browser QueryClient. The main case this improves is a later dehydrated payload updating queries that already exist and have active observers, such as a client navigation.

Right now each updated query schedules its own notification flush. Wrapping each HydrationBoundary hydrate pass in notifyManager.batch keeps every observer callback, but flushes the scheduled callbacks together. For N observed queries, scheduled flushes drop from N to 1 without adding another scheduler tick.

This only changes @tanstack/react-query HydrationBoundary. The official @tanstack/react-router-ssr-query integration used by TanStack Start calls the core hydrate API directly, so that path is not affected by this PR.

The benchmark hydrates existing queries with active QueryObserver subscriptions through notifyManager.batchCalls, matching the React subscription path.

Vitest benchmark

Observed queries	Before	After	Speedup
10	170,049 ops/s	182,103 ops/s	1.07x
25	64,924 ops/s	72,821 ops/s	1.12x
50	33,526 ops/s	36,224 ops/s	1.08x

Summary by CodeRabbit

• Performance Improvements
  • Batched query notifications during hydration to reduce unnecessary updates and improve rendering efficiency.
  • Applied batching consistently during both initial hydration and follow-up hydration updates.

[coderabbitai]

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: 235bec12-c3b9-4f14-af22-e33b5abe851f

📥 Commits

Reviewing files that changed from the base of the PR and between b8e3559 and 7467628.

📒 Files selected for processing (2)

• .changeset/faster-react-hydration.md
• packages/react-query/src/HydrationBoundary.tsx

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

HydrationBoundary now batches notifications for render-time hydration of new queries and effect-time hydration of queued existing queries. A patch changeset documents the update.

Changes

React hydration batching

Layer / File(s)	Summary
Batch hydration notifications packages/react-query/src/HydrationBoundary.tsx, .changeset/faster-react-hydration.md	HydrationBoundary wraps both hydration paths in notifyManager.batch. The changeset records a patch release for @tanstack/react-query.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Merge Risk: ⚪ Minimal · up to 74676

This localized change batches React hydration notifications to reduce redundant flushes without changing the hydration API; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• TanStack/query#11137: Both changes modify HydrationBoundary hydration behavior.
• TanStack/query#11157: Both changes modify hydration behavior and query hydration sequencing.

Suggested labels: package: react-query

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes batching hydration notifications in React Query.
Description check	✅ Passed	The description clearly explains the change, motivation, scope, and benchmark, but it omits the template's checklist and release-impact sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[scttcper]

i'm not really sold on the safety of this one and i don't use nextjs