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

# Quickstart

> Install @convex-dev/react-query and make your first reactive query in under 5 minutes.

<Steps>
  <Step title="Install">
    Add the adapter and its peer dependencies to your project.

    <CodeGroup>
      ```bash npm theme={null}
      npm install @convex-dev/react-query @tanstack/react-query convex
      ```

      ```bash yarn theme={null}
      yarn add @convex-dev/react-query @tanstack/react-query convex
      ```

      ```bash pnpm theme={null}
      pnpm add @convex-dev/react-query @tanstack/react-query convex
      ```
    </CodeGroup>
  </Step>

  <Step title="Create ConvexQueryClient">
    Initialize the Convex client, the `ConvexQueryClient` adapter, and the TanStack `QueryClient` together. Do this once at the module level, outside any component.

    ```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);
    ```

    <Note>
      The `queryKeyHashFn` must be set globally — it cannot be set per-query, so the client can correctly identify and update Convex query cache entries.
    </Note>
  </Step>

  <Step title="Wrap your app">
    Place `ConvexProvider` and `QueryClientProvider` around your application. Both providers are required: `ConvexProvider` enables Convex hooks like `useConvexMutation`, while `QueryClientProvider` makes the TanStack cache available to `useQuery`.

    ```tsx theme={null}
    import { ConvexProvider } from "convex/react";
    import { QueryClientProvider } from "@tanstack/react-query";

    function Main() {
      return (
        <ConvexProvider client={convexClient}>
          <QueryClientProvider client={queryClient}>
            <App />
          </QueryClientProvider>
        </ConvexProvider>
      );
    }
    ```
  </Step>

  <Step title="Make your first reactive query">
    Use `convexQuery()` as the options argument to `useQuery`. Pass your generated `api` object and any query arguments.

    ```tsx theme={null}
    import { useQuery } from "@tanstack/react-query";
    import { convexQuery } from "@convex-dev/react-query";
    import { api } from "../convex/_generated/api";

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

      if (isPending) return <div>Loading...</div>;
      if (error) return <div>Error: {error.message}</div>;
      return (
        <ul>
          {data.map((message) => (
            <li key={message._id}>{message.body}</li>
          ))}
        </ul>
      );
    }
    ```

    <Info>
      The query subscribes via WebSocket and updates automatically whenever the server data changes. No polling needed.
    </Info>
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Reactive queries" icon="bolt" href="/guides/queries">
    Learn how to use `convexQuery` with conditional queries, `useSuspenseQuery`, and custom options like `placeholderData`.
  </Card>

  <Card title="Mutations & actions" icon="pencil" href="/guides/mutations-and-actions">
    Use `useConvexMutation` and `useConvexAction` with TanStack Query's `useMutation` hook.
  </Card>

  <Card title="Authentication" icon="lock" href="/guides/authentication">
    Integrate Convex Auth, Clerk, or another auth provider with the query adapter.
  </Card>

  <Card title="API reference" icon="book" href="/api/convex-query-client">
    Full reference for `ConvexQueryClient`, `convexQuery`, `convexAction`, and all re-exported hooks.
  </Card>
</CardGroup>