Skip to main content

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

new ConvexQueryClient(client, options?)
​
client
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.
​
options
ConvexQueryClientOnlyOptions | ConvexQueryClientOptions
When client is a ConvexReactClient, accepts ConvexQueryClientOnlyOptions. When client is a URL string, accepts ConvexQueryClientOptions (which extends ConvexQueryClientOnlyOptions with ConvexReactClientOptions).

​
ConvexQueryClientOnlyOptions

​
queryClient
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.
​
serverFetch
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.
​
dangerouslyUseInconsistentQueriesDuringSSR
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.

​
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

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.
​
queryClient
QueryClient
required
The TanStack Query QueryClient to connect to.
Calling connect more than once, or calling it after passing queryClient in the constructor options, throws an error.

​
queryFn

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.
​
otherFetch
QueryFunction
Optional fallback QueryFunction for non-Convex query keys. Defaults to a function that throws an error for unrecognized keys.

​
hashFn

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.
​
otherHashKey
(queryKey: ReadonlyArray<unknown>) => string
Optional fallback hash function for non-Convex query keys. Defaults to hashKey from @tanstack/react-query.

​
queryOptions

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.
​
funcRef
FunctionReference<'query'>
required
The Convex query function reference, imported from convex/_generated/api.
​
queryArgs
FunctionArgs<typeof funcRef>
required
The arguments to pass to the query function.
Because TanStack Query does not support per-query queryKeyHashFn overrides, you must still set queryKeyHashFn: convexQueryClient.hashFn() globally on the QueryClient when using queryOptions.

​
Properties

​
convexClient
ConvexReactClient
The underlying ConvexReactClient instance used for WebSocket subscriptions and queries.
​
subscriptions
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.

​
Setup example

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: 
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: ... } } })
The queryKeyHashFn and queryFn are configured on the QueryClient, not on ConvexQueryClient. Always set them in QueryClient’s defaultOptions.queries.

Build docs developers (and LLMs) love

Get started for freeTalk to us