Convex with TanStack Start

Using React Query hooks for data from Convex

TanStack Start apps can use React Query (TanStack Query for React) hooks to take advantage of React Query's excellent Start integration. Convex queries are exposed through query options factories like convexQuery().

Instead of React Query's standard interval and activity-based polling and manual invalidation, updates are streamed down WebSocket to update the Query Cache directly for live, always-up-to-date results.

Open this page in another tab or on your phone and send a message or to see these updates pushed live.

9
User 90445/21/25, 9:35 AM

hello Nipunn! I'll be late to make the meeting tomorrow morning

4
User 46325/21/25, 9:34 AM

hey Nipunn- how's the weather in SF?

9
User 92445/21/25, 9:34 AM

hello James, what's your favorite ice cream place?

9
User 92445/21/25, 9:34 AM

hi James... how's the weather in SF?

9
User 92445/21/25, 9:34 AM

Hi Nipunn! I'll be late to make the meeting tomorrow morning

9
User 95015/20/25, 3:09 PM

hello James; Could you let the customer know we've fixed their issue?

9
User 95015/20/25, 3:09 PM

hey Nipunn; Could you let the customer know we've fixed their issue?

9
User 95015/20/25, 3:09 PM

hi James... Could you let the customer know we've fixed their issue?

7
User 715/20/25, 3:08 PM

Hi James; how was your weekend?

3
User 3755/20/25, 3:08 PM

Hi Emma- what's your favorite ice cream place?

2
User 2795/20/25, 3:08 PM

hi Nipunn! how's the weather in SF?

6
User 6775/20/25, 3:08 PM

hey Jamie, what's your favorite ice cream place?

1
User 1615/20/25, 3:08 PM

Hi Nipunn! I'll be late to make the meeting tomorrow morning

3
User 3655/20/25, 3:08 PM

hello Jamie! I'll be late to make the meeting tomorrow morning

1
User 1875/20/25, 3:08 PM

hello Nipunn... how's the weather in SF?

8
User 8215/20/25, 3:08 PM

hello James... how's the weather in SF?

5
User 5645/20/25, 3:08 PM

Hi James; Could you let the customer know we've fixed their issue?

1
User 1185/20/25, 3:08 PM

hey Jamie... what's your favorite ice cream place?

9
User 9075/20/25, 3:08 PM

hello Nipunn, how was your weekend?

5
User 5215/20/25, 3:08 PM

hello Nipunn... I'll be late to make the meeting tomorrow morning

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

5const messagesQuery = convexQuery(
6  api.messages.listMessages,
7  { channel: "chatty" }
8)
9

10// inside a React component
11const { data, isPending } = useQuery(messagesQuery);
12

13// in an event handler, useEffect, or loader
14queryClient.prefetchQuery(messagesQuery);
15

16// adding more query options to convexQuery()
17const { data } = useQuery({
18  ...convexQuery(api.messages.listMessages, {}),
19  initialData: [],
20  gcTime: 10000,
21});

Already used Convex React hooks?

If you've used Convex React hooks React Query hooks are going to familiar. Instead of returning the data directly, this useQuery() returns an object with a .data property along with other metadata. The hook accepts a single object, which you'll mostly populate with the return value of the convexQuery()hook.

The same React Query hooks can be used for fetch endpoints and Convex actions for standard interval or activity-based polling while Convex queries benefit from the live update behavior.

What does this give you? It's not just the often-asked-for isLoading and error properties or simple interop with other server endpoints or introspection from the TanStack Query devtools. It's React Query's Router integration with the TanStack Start providing things like server-side rendering and live updating queries in a single hook.

Learn More

TanStack Query (AKA React Query) docs

Using TanStack Query with Convex

The @convex-dev/react-query library links the TanStack Query Client with the Convex client