Introduction

Learn what @convex-dev/react-query is and how it fits into your stack.

What is this library?

@convex-dev/react-query is an adapter that lets you use TanStack Query (useQuery, useSuspenseQuery, and the rest of the TanStack Query API) with Convex real-time subscriptions.

Rather than polling for new data, results are pushed from the server to the client via WebSocket. Whenever a Convex query function’s result changes, the TanStack Query cache is updated automatically — no queryClient.invalidateQueries() calls required.

When to use it

This library is a good fit when:

• You are already using TanStack Query in a Convex app and want to keep using useQuery without switching to Convex’s own useQuery hook.
• You want access to TanStack Query DevTools, caching semantics (gcTime, placeholderData, etc.), and the broader TanStack Query ecosystem alongside Convex’s real-time data layer.
• You are building a server-side rendered app with TanStack Start or a similar framework and want consistent query results during SSR.

Key concepts

ConvexQueryClient

Bridges the Convex client and the TanStack QueryClient. Subscribes to the query cache, opens WebSocket subscriptions for each Convex query, and pushes updated results into the cache as they arrive.

convexQuery()

Options factory for reactive query subscriptions. Pass it directly to useQuery or useSuspenseQuery. Sets staleTime: Infinity and constructs the correct query key automatically.

convexAction()

Options factory for Convex actions used as queries. Actions are not reactive — they follow standard TanStack Query refetch semantics rather than receiving server-pushed updates.

Re-exported hooks

useConvexMutation, useConvexAction, useConvexQuery, useConvexQueries, useConvexPaginatedQuery, useConvex, and useConvexAuth are all re-exported so you can avoid importing from convex/react directly.

Peer dependencies

Package	Version
@tanstack/react-query	^5.0.0
convex	^1.34.1

Install them alongside the adapter:

npm install @convex-dev/react-query @tanstack/react-query convex

Why staleTime: Infinity?

Both convexQuery() and convexAction() set staleTime: Infinity. For Convex queries, data is never stale — the server pushes a new result the moment the underlying data changes. There is no need for TanStack Query to re-fetch in the background; refetching would only duplicate work already handled by the WebSocket subscription.

You can still tune gcTime to control how long a subscription stays active after all useQuery hooks using it have unmounted. A value of a few seconds avoids tearing down and rebuilding subscriptions during page transitions.

Ready to add this to your project? See the Quickstart to get up and running in a few minutes.