> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/get-convex/convex-react-query/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CardGroup cols={2}>
  <Card title="ConvexQueryClient" icon="plug">
    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.
  </Card>

  <Card title="convexQuery()" icon="bolt">
    Options factory for reactive query subscriptions. Pass it directly to `useQuery` or `useSuspenseQuery`. Sets `staleTime: Infinity` and constructs the correct query key automatically.
  </Card>

  <Card title="convexAction()" icon="play">
    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.
  </Card>

  <Card title="Re-exported hooks" icon="code">
    `useConvexMutation`, `useConvexAction`, `useConvexQuery`, `useConvexQueries`, `useConvexPaginatedQuery`, `useConvex`, and `useConvexAuth` are all re-exported so you can avoid importing from `convex/react` directly.
  </Card>
</CardGroup>

## Peer dependencies

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

Install them alongside the adapter:

```bash theme={null}
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.

<Tip>
  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.
</Tip>

Ready to add this to your project? See the [Quickstart](/quickstart) to get up and running in a few minutes.