utility hook (usePolymorphicQuery) to help gradual v4 -> v5 migration?

[toothlessdev]

Hello TanStack Team & Community,

First, I just want to say I'm a huge fan of the v5 API.
The split between useQuery and useSuspenseQuery is a fantastic design choice. It makes our architectural decisions (component-driven state vs. Suspense-driven state) much more explicit and type-safe.

I'd like to start a discussion around the migration path for teams with large, existing v4 codebases.

In v4, suspense: true was a very flexible option. Migrating these codebases to v5 isn't just a simple find-and-replace; it often requires a significant refactor to implement the correct and boundaries, which can feel like an "all-or-nothing" task.

Idea for Discussion:

What are your thoughts on introducing an optional migration utility hook? (Let's call it usePolymorphicQuery for now).

This hook would essentially be a v5-compatible wrapper that mimics the v4 behavior:

It would take a suspense: boolean argument.

It would use function overloading to correctly infer the options and return types (e.g., data: T vs. data: T | undefined) based on that flag.

Internally, it would just delegate to useQuery or useSuspenseQuery.

The main goal would be to enable a much more gradual migration. Teams could adopt v5, use this utility as a temporary bridge to get their app running, and then refactor route-by-route to the explicit useSuspenseQuery hook as they're ready. It lowers that initial adoption barrier significantly.

I fully respect that this is counter to the final design goal of v5 (which is to be explicit), so this would strictly be an opt-in utility to help people on their journey.

Does this sound like something that would be valuable to the community? If this idea gains traction and the team is open to it, I'd be happy to try and put together a PR.

thank you

[TkDodo]

Internally, it would just delegate to useQuery or useSuspenseQuery.

Why wouldn’t you build that in user-land? Note that calling a query conditionally depending on a boolean param is against the rules of hooks in react, but you can maybe build it on top of useBaseQuery.

The split between useQuery and useSuspenseQuery is a fantastic design choice.

Thanks, but we’re actually re-considering it given how react and use() work right now 😅. One idea is to have:

const { promise } = useQuery(...)

and then have users do:

const data = use(promise)

wherever they want, even conditionally, to suspend. It’s already available but needs an experimental flag (experimental_prefetchInRender) turned on.

Maybe you’d want to try out this as a migration path if you’re on React v19 ?

[toothlessdev]

The use(promise) approach for React 19 makes perfect sense
it’s really helpful to understand the intended migration direction.

Thanks a lot for the detailed context 😄