> ## 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.

# ConvexQueryClient

> API reference for the ConvexQueryClient class that bridges Convex subscriptions and TanStack Query.

`ConvexQueryClient` subscribes to events from a TanStack Query `QueryClient` and populates query results for all Convex query function subscriptions. It manages WebSocket subscriptions through the Convex client and keeps TanStack Query's cache up to date with pushed updates.

## Constructor

```ts theme={null}
new ConvexQueryClient(client, options?)
```

<ParamField path="client" type="ConvexReactClient | string" required>
  A `ConvexReactClient` instance, or a Convex deployment URL string. When a URL string is provided, a `ConvexReactClient` is created automatically using the options passed.
</ParamField>

<ParamField path="options" type="ConvexQueryClientOnlyOptions | ConvexQueryClientOptions">
  When `client` is a `ConvexReactClient`, accepts `ConvexQueryClientOnlyOptions`. When `client` is a URL string, accepts `ConvexQueryClientOptions` (which extends `ConvexQueryClientOnlyOptions` with `ConvexReactClientOptions`).
</ParamField>

### ConvexQueryClientOnlyOptions

<ParamField path="queryClient" type="QueryClient">
  Pass a `QueryClient` to connect immediately. This is an alternative to calling `.connect()` after construction. If omitted, you must call `.connect(queryClient)` before using the client.
</ParamField>

<ParamField path="serverFetch" type="typeof globalThis.fetch | undefined">
  A custom fetch implementation for server-side HTTP requests. Take care to avoid bundling this implementation on the client. In TanStack Start, use `createServerOnlyFn` for this purpose.
</ParamField>

<ParamField path="dangerouslyUseInconsistentQueriesDuringSSR" type="boolean" default="false">
  Opt out of consistent SSR queries. When `false` (the default), consistent mode uses two round trips to ensure all queries share the same database snapshot. Set to `true` for faster SSR at the cost of potential inter-query inconsistency — for example, a `favChannelIds` query might reference a channel ID that is absent from a simultaneously fetched `channels` query.
</ParamField>

### ConvexQueryClientOptions

`ConvexQueryClientOptions` extends both `ConvexQueryClientOnlyOptions` and `ConvexReactClientOptions`. It is used when passing a URL string as the `client` argument, allowing you to configure both the underlying `ConvexReactClient` and the `ConvexQueryClient` in one options object.

## Methods

### connect

```ts theme={null}
connect(queryClient: QueryClient): void
```

Connects the `ConvexQueryClient` to a TanStack `QueryClient`. Must be called exactly once, unless a `queryClient` was passed in the constructor options. Starts listening to `QueryCache` events to manage Convex subscriptions.

<ParamField path="queryClient" type="QueryClient" required>
  The TanStack Query `QueryClient` to connect to.
</ParamField>

<Warning>
  Calling `connect` more than once, or calling it after passing `queryClient` in the constructor options, throws an error.
</Warning>

***

### queryFn

```ts theme={null}
queryFn(otherFetch?: QueryFunction): QueryFunction
```

Returns a TanStack Query `queryFn` that handles `convexQuery` and `convexAction` query keys. Pass the result as the global `queryFn` in your `QueryClient` default options.

On the server, queries are executed via HTTP (`ConvexHttpClient`). On the client, they run via the WebSocket connection and the result is returned from the local cache once available.

<ParamField path="otherFetch" type="QueryFunction">
  Optional fallback `QueryFunction` for non-Convex query keys. Defaults to a function that throws an error for unrecognized keys.
</ParamField>

***

### hashFn

```ts theme={null}
hashFn(otherHashKey?: (queryKey: ReadonlyArray<unknown>) => string): (queryKey: ReadonlyArray<unknown>) => string
```

Returns a `queryKeyHashFn` for TanStack Query that correctly serializes Convex `FunctionReference` objects using `getFunctionName()` and `convexToJson()`. Pass the result as the global `queryKeyHashFn` in your `QueryClient` default options.

<ParamField path="otherHashKey" type="(queryKey: ReadonlyArray<unknown>) => string">
  Optional fallback hash function for non-Convex query keys. Defaults to `hashKey` from `@tanstack/react-query`.
</ParamField>

***

### queryOptions

```ts theme={null}
queryOptions(
  funcRef: FunctionReference<"query">,
  queryArgs: FunctionArgs<typeof funcRef>
): Pick<UseQueryOptions, "queryKey" | "queryFn" | "staleTime">
```

Returns query options for `useQuery` or `useSuspenseQuery`. Unlike `convexQuery()`, this method embeds the `queryFn` directly in the returned options object, so it does not require the global default `queryFn` to be set on the `QueryClient`.

<ParamField path="funcRef" type="FunctionReference<'query'>" required>
  The Convex query function reference, imported from `convex/_generated/api`.
</ParamField>

<ParamField path="queryArgs" type="FunctionArgs<typeof funcRef>" required>
  The arguments to pass to the query function.
</ParamField>

<Note>
  Because TanStack Query does not support per-query `queryKeyHashFn` overrides, you must still set `queryKeyHashFn: convexQueryClient.hashFn()` globally on the `QueryClient` when using `queryOptions`.
</Note>

## Properties

<ResponseField name="convexClient" type="ConvexReactClient">
  The underlying `ConvexReactClient` instance used for WebSocket subscriptions and queries.
</ResponseField>

<ResponseField name="subscriptions" type="Record<string, { watch: Watch<any>; unsubscribe: () => void; queryKey: [...] }>">
  Internal map of active Convex subscriptions, keyed by the TanStack Query hash of the query key. Each entry holds the `Watch` object and its unsubscribe function. Do not modify this directly.
</ResponseField>

## Setup example

```ts theme={null}
import { ConvexReactClient } from "convex/react";
import { QueryClient } from "@tanstack/react-query";
import { ConvexQueryClient } from "@convex-dev/react-query";

const convexClient = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);
const convexQueryClient = new ConvexQueryClient(convexClient);
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: convexQueryClient.hashFn(),
      queryFn: convexQueryClient.queryFn(),
    },
  },
});
convexQueryClient.connect(queryClient);
```

Alternatively, pass a URL string and supply `queryClient` directly in the options to skip the manual `connect` call:

```ts theme={null}
import { QueryClient } from "@tanstack/react-query";
import { ConvexQueryClient } from "@convex-dev/react-query";

const queryClient = new QueryClient();
const convexQueryClient = new ConvexQueryClient(
  import.meta.env.VITE_CONVEX_URL,
  { queryClient }
);
// Still set hashFn and queryFn on the QueryClient's default options:
// queryClient = new QueryClient({ defaultOptions: { queries: { queryKeyHashFn: ..., queryFn: ... } } })
```

<Note>
  The `queryKeyHashFn` and `queryFn` are configured on the `QueryClient`, not on `ConvexQueryClient`. Always set them in `QueryClient`'s `defaultOptions.queries`.
</Note>