Convex React Query

Real-time reactive Convex queries with TanStack Query — zero polling, zero stale data.

@convex-dev/react-query bridges Convex real-time subscriptions with TanStack Query, giving you live-updating data in your React app without polling or manual cache invalidation.

When a Convex query result changes on the server, the update is pushed to your client instantly. Your TanStack Query cache stays fresh automatically — no queryClient.invalidateQueries() needed.

Quickstart

Install the package and wire up your first reactive query in minutes.

How it works

Learn how Convex subscriptions integrate with the TanStack Query cache.

API Reference

Full reference for ConvexQueryClient, convexQuery, and convexAction.

Guides

Deep dives into queries, mutations, authentication, and SSR.

Why use this library?

Convex pushes new query results to your client over a WebSocket whenever the underlying data changes. TanStack Query is the most popular data-fetching library for React. This adapter connects them so you can use the full TanStack Query API — useQuery, useSuspenseQuery, useMutation, devtools, and more — while getting Convex’s real-time guarantees for free.

No stale data

Results are pushed from the server; staleTime: Infinity is set automatically so TanStack Query never marks Convex data as stale.

No manual invalidation

Forget invalidateQueries(). The ConvexQueryClient updates the cache whenever the server pushes a new result.

Type-safe queries

Full TypeScript inference for function arguments and return types using Convex’s generated api object.

SSR ready

Fetch consistent query snapshots on the server with ConvexHttpClient and hydrate on the client.

Quick look

quickstart.tsx

import { useQuery } from "@tanstack/react-query";
import { convexQuery } from "@convex-dev/react-query";
import { api } from "../convex/_generated/api";

function MessageList() {
  const { data, isPending } = useQuery(convexQuery(api.messages.list, {}));

  if (isPending) return <div>Loading...</div>;
  return (
    <ul>
      {data.map((msg) => (
        <li key={msg._id}>{msg.body}</li>
      ))}
    </ul>
  );
}

1. Install the package

   Add @convex-dev/react-query along with its peer dependencies.

   npm install @convex-dev/react-query @tanstack/react-query convex
   
2. Create ConvexQueryClient

   Instantiate a ConvexQueryClient and connect it to your TanStack QueryClient.

   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);
   
3. Wrap your app

   Provide both clients to your React tree.

   <ConvexProvider client={convexClient}>
     <QueryClientProvider client={queryClient}>
       <App />
     </QueryClientProvider>
   </ConvexProvider>
   
4. Query with convexQuery

   Use useQuery with the convexQuery options factory for live-updating data.

   const { data } = useQuery(convexQuery(api.messages.list, {}));