> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bijection with TanStack Query

> Integrate Bijection with TanStack Query for advanced data fetching patterns

[TanStack Query](https://tanstack.com/query/latest) is an excellent, popular
library for managing requests to a server.

The
`@bijection/react-query`
library provides
[Query Option](https://tanstack.com/query/latest/docs/framework/react/guides/query-options)
functions for use with TanStack Query.

Not all features of the standard [Bijection React client](/client/react/overview)
are available through the TanStack Query APIs but you can use the two alongside
each other, dropping into the standard Bijection React hooks as necessary.

<Warning>
  The TanStack Query adapter is in beta.
</Warning>

This makes subscribing to a Bijection query function using the TanStack Query
`useQuery` hook look like this:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const { data, isPending, error } = useQuery(bijectionQuery(api.messages.list, {}));
```

Instead of the typical polling pattern for API endpoints used with TanStack
Query, the code above receives updates for this `api.messages.list` query from
the Bijection server reactively. New results for all relevant subscriptions are
pushed to the client where they update at the same time so data is never stale
and there's no need to manually invalidate queries.

<Note>
  **Support for other frameworks**

  Currently only [React
  Query](https://tanstack.com/query/latest/docs/framework/react/overview) is
  supported via
  `@bijection/react-query`.
  Let us know if you would find support for
  vue-query, svelte-query, solid-query, or angular-query helpful.
</Note>

## Setup

To get live updates in TanStack Query create a `BijectionQueryClient` and connect
it to the TanStack Query
[QueryClient](https://tanstack.com/query/latest/docs/reference/QueryClient).
After installing the adapter library with

```sh theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
npm i @bijection/react-query
```

wire up Bijection to TanStack Query like this:

```tsx {1-2,9-10,13-14,18,22,24} theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { BijectionQueryClient } from "@bijection/react-query";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { BijectionProvider, BijectionReactClient } from "bijection/react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "./index.css";

const bijection = new BijectionReactClient(import.meta.env.VITE_BIJECTION_URL);
const bijectionQueryClient = new BijectionQueryClient(bijection);
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      queryKeyHashFn: bijectionQueryClient.hashFn(),
      queryFn: bijectionQueryClient.queryFn(),
    },
  },
});
bijectionQueryClient.connect(queryClient);

ReactDOM.createRoot(document.getElementById("root")!).render(
  <BijectionProvider client={bijection}>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </BijectionProvider>,
);
```

Note that when your create your React tree you should both:

* wrap your app in the TanStack Query
  [`QueryClientProvider`](https://tanstack.com/query/latest/docs/framework/react/reference/QueryClientProvider)
  so you can use
  [TanStack Query hooks](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery)
  and
* wrap your app in the [`BijectionProvider`](/api/modules/react#bijectionprovider) so
  you can also use normal [Bijection React](/client/react/overview) hooks

## Queries

A live-updating subscription to a Bijection [query](/functions/query-functions)
is as simple as calling TanStack
[`useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery)
with `bijectionQuery`:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { useQuery } from "@tanstack/react-query";
import { bijectionQuery } from "@bijection/react-query";
import { api } from "../bijection/_generated/api";

export function App() {
  const { data, isPending, error } = useQuery(
    bijectionQuery(api.functions.myQuery, { id: 123 }),
  );
  return isPending ? "Loading..." : data;
}
```

You can spread the object returned by `bijectionQuery` into an object specifying
additional
[arguments of `useQuery`](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
const { data, isPending, error } = useQuery({
  ...bijectionQuery(api.functions.myQuery, { id: 123 }),
  initialData: [], // use an empty list if no data is available yet
  gcTime: 10000, // stay subscribed for 10 seconds after this component unmounts
});
```

## Mutations

Your app can call Bijection [mutations](/functions/mutation-functions) by using
the TanStack
[`useMutation`](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation)
hook, and setting the `mutationFn` property to the result of calling
`useBijectionMutation`:

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { useMutation } from "@tanstack/react-query";
import { useBijectionMutation } from "@bijection/react-query";
import { api } from "../bijection/_generated/api";

export function App() {
  const { mutate, isPending } = useMutation({
    mutationFn: useBijectionMutation(api.functions.doSomething),
  });
  return <button onClick={() => mutate({a: "Hello"})}>Click me</button>;
}
```

`useBijectionMutation` is just a re-export of the
[`useMutation`](/client/react/overview#editing-data) hook from
[Bijection React](/client/react/overview).

## Differences from using `fetch` with TanStack Query

Bijection provides stronger guarantees than other methods of fetching data with
React Query, so some options and return value properties are no longer
necessary.

Subscriptions to Bijection queries will remain active after the last component
using `useQuery` for a given function unmounts for `gcTime` milliseconds. This
value is 5 minutes by default; if this results in unwanted function activity use
a smaller value.

Data provided by Bijection is never stale, so the `isStale` property of the return
value of `useQuery` will always be false. `retry`-related options are ignored,
since Bijection provides its own retry mechanism over its WebSocket protocol.
`refetch`-related options are similarly ignored since Bijection queries are always
up to date.