Bijection with TanStack Query

TanStack Query is an excellent, popular library for managing requests to a server. The @bijection/react-query library provides Query Option functions for use with TanStack Query. Not all features of the standard Bijection React client 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.

The TanStack Query adapter is in beta.

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

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.

Support for other frameworksCurrently only React Query 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.

Setup

To get live updates in TanStack Query create a BijectionQueryClient and connect it to the TanStack Query QueryClient. After installing the adapter library with

npm i @bijection/react-query

wire up Bijection to TanStack Query like this:

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 so you can use TanStack Query hooks and
wrap your app in the BijectionProvider so you can also use normal Bijection React hooks

Queries

A live-updating subscription to a Bijection query is as simple as calling TanStack useQuery with bijectionQuery:

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.

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 by using the TanStack useMutation hook, and setting the mutationFn property to the result of calling useBijectionMutation:

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 hook from Bijection React.

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.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Bijection with TanStack Query

Setup

Queries

Mutations

Differences from using `fetch` with TanStack Query

​Setup

​Queries

​Mutations

​Differences from using fetch with TanStack Query

Setup

Queries

Mutations

Differences from using `fetch` with TanStack Query