feat(react-query): add react@19 as peerDeps

[gwansikk]

related: #8441

I'm the maintainer of Suspensive (a community project for React Query), who previously submitted a PR regarding React 19 support in React Query v4.

This PR, I'd like to explicitly specify React 19 in the peerDependencies instead of the dependencies. React Query v4 is already compatible with React 19 without any code changes, and we've confirmed this through the following steps:

• Built a custom tarball package(pnpm pack) with React 19 specified in peerDependencies
• Linked the tarball in a React 19 environment for testing
• Confirmed that it works without issues (we were able to resolve previously occurring warnings and errors)

There are no breaking changes in React 19 that affect compatibility, and v4 works reliably without special handling. If issues do arise, they would likely be due to changes in React 19, not React Query v4 itself.

Currently, since React 19 is not listed in peerDependencies, using react-query@v4 in a React 19 environment causes the following problems:

• Peer dependency warnings are triggered by the package manager
• Community libraries built on top of React Query v4 may face confusion when trying to support React 19

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 7c44694

Command	Status	Duration	Result
nx affected --targets=test:lib,test:types,test:...	✅ Succeeded	32s	View ↗
nx affected --targets=test:lib --base=1b5c25630...	✅ Succeeded	15s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-10-14 16:58:43 UTC

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 7c44694:

Sandbox	Source
@tanstack/query-example-react-basic-typescript	Configuration
@tanstack/query-example-solid-basic-typescript	Configuration
@tanstack/query-example-vue-basic	Configuration

[gwansikk]

I can't reproduce the issue in the local test environment. Is there a problem with the CI pipeline?

[manudeli]

I’m in favor of adding React 19 to the peerDependencies of @tanstack/react-query v4.
Since it seems that @TkDodo previously opposed this change, I wanted to tag you and check if you’re okay with it before merging.

From what I understand, there’s nothing in @tanstack/react-query v4 that should cause issues with React 19.
If there are any problems, I’d expect them to be due to changes in React itself — so I think it should be safe to go ahead with the merge. Would that be alright with you?

[TkDodo]

we can bump the peerDependency if everything works at runtime, but I don’t think we’re running tests against react19.

[multipletwigs]

@gwansikk appreciate the PR here, really timely as I'm about to do a major migration to v5 just to support React 19. Do you have any timeline on this?

[gwansikk]

@gwansikk appreciate the PR here, really timely as I'm about to do a major migration to v5 just to support React 19. Do you have any timeline on this?

The current work is in its final stages. However, in order for the PR to be merged, sufficient discussion with the maintainer is necessary.

#8441 (comment)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

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

---

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

[gwansikk]

Latest passing test:

https://cloud.nx.app/runs/IUqpad7wPG

[gwansikk]

NX CI is broken; all tests pass locally.

[gwansikk]

This PR is fully prepared. Could you please take a look?
@manudeli

[manudeli]

This PR is fully prepared. Could you please take a look? @manudeli

I'll see this until next week.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 7c44694

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

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

[gwansikk]

When useErrorBoundary is passed as a function to useMutation,
in React 19, this function is called three times, and since the last call returns false,
the error is not passed to the ErrorBoundary but instead rendered inside the component.
(In React 18, it was called twice and worked correctly.)

Due to React 19's changed render sequence, the React Query Observer runs three times.
To fix this, we are updating the logic to a count-based approach that doesn't rely on render counts (i.e., not using !boundary logic).

[gwansikk]

This part also has different state tests due to the changed render sequence in React 19.
We’ve clearly separated the handling logic according to each React version.

[gwansikk]

@manudeli All test adaptations have been completed!

What I’d like to convey to the maintainer is that the test environment is tightly coupled with the internal render behavior (number of renders), which varies depending on the React version.
Should we really be relying on the number of renders? It has proven to be changeable across versions.
— As a result, we had no choice but to introduce version-specific branching logic(e.g. reactVersion() === '19') in the test code to properly handle different React versions.