#useQuery vs react-query

1 messages · Page 1 of 1 (latest)

hoary bridge
#

When do you advise to use useQuery from convex vs tanstack's useQuery? what are the pros/cons of each?

cloud topazBOT
#

Hi @hoary bridge. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

Great question! Both options work well with Convex, but they shine in different scenarios.

When to use Convex’s useQuery (from convex/react)

  • Best for: Simplicity and fully reactive Convex apps without extra libraries.
  • Behavior:
    • Subscribes to your Convex query and keeps components updated automatically when data changes—no manual invalidation, no polling. [Fetching data]
    • Ensures consistent results across your app at a single logical timestamp. [Fetching data]
    • Multiple components using the same query share a single subscription; no duplicate requests. [Query cache usage]
  • Pros:
    • Easiest setup and mental model for Convex.
    • Strong consistency guarantees and automatic live updates.
  • Cons:
    • Doesn’t integrate with TanStack Query’s devtools or its broader ecosystem by default.
    • Some advanced cache behaviors (e.g., keeping data alive across page transitions) may require patterns like lifting a query higher or using helpers. [convex-react-query state]
#

When to use TanStack’s useQuery with @convex-dev/react-query

  • Best for: Apps using TanStack Start/React Query where you want SSR, loaders, and React Query tooling with Convex’s live updates.
  • Behavior:
    • You call useQuery(convexQuery(...)) to get a live subscription backed by Convex over WebSocket—no manual invalidation, data is never stale. [Queries; Differences]
    • Subscriptions persist after unmount for gcTime (default 5 minutes), so client navigations can feel instant if the query was recently used. [Differences; TanStack Start]
  • Pros:
    • Works seamlessly with TanStack Start SSR, loaders, and Suspense; easiest path to SSR + live updates. [TanStack Start]
    • Keeps subscriptions alive via React Query’s cache window (gcTime) for smoother back/forward nav. [TanStack Start]
    • Access to React Query ecosystem (e.g., devtools).
  • Cons:
    • Some Convex React features aren’t available via the adapter; you may still use standard Convex hooks alongside it for those. [Convex with TSQ]
    • A few TanStack options don’t apply (retry/refetch/stale) because Convex subscriptions keep data fresh automatically. [Differences]
    • The adapter is in beta. [Convex with TSQ]
#

Practical guidance

  • If you’re not using TanStack Start or React Query already: prefer Convex’s useQuery for the simplest, most “native Convex” experience. [Convex with TSQ]
  • If you are using TanStack Start or want SSR/loaders/Suspense/devtools: use TanStack’s useQuery with convexQuery; it gives you live Convex data with React Query ergonomics. [TanStack Start; Queries]
  • You can mix them: both share the same Convex client, so results stay consistent if you combine TanStack and Convex hooks. [TanStack Start]

Notes on auth and edge cases

  • If you run into auth timing issues with the adapter (rare, beta): standard convex/react useQuery doesn’t show the same race, per a community report. [Auth context bug]

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: