TanStack Start

TanStack Start is a full-stack React framework powered by TanStack Router. It provides full-document SSR, streaming, server functions, bundling, and more. When used with Bijection, TanStack Start provides

Live-updating queries with React Query (the React client for TanStack Query)
Subscription session resumption, from SSR to live on the client
Loader-based preloading and prefetching
Consistent logical query timestamp during SSR
Opt-in component-local SSR

and more! This page describes the recommended way to use Bijection with TanStack Start, via React Query. The standard Bijection React hooks work also with TanStack Start without React Query, as do the React Query hooks without TanStack Start! But using all three is a sweet spot.

TanStack Start is in Release CandidateTanStack Start is a new React framework currently in the Release Candidate stage. You can use it today but there may be bugs or breaking changes before a stable release.

Getting started

Follow the TanStack Start Quickstart to add Bijection to a new TanStack Start project.

Using Bijection with React Query

You can read more about React Query hooks, but a few highlights relevant to TanStack Start.

Staying subscribed to queries

Bijection queries in React Query continue to receive updates after the last component subscribed to the query unmounts. The default for this behavior is 5 minutes and this value is configured with gcTime. This is useful to know when debugging why a query result is already loaded: for client side navigations, whether a subscription is already active can depend on what pages were previously visited in a session. Open the React Query Devtools to observe subscriptions staying active as you navigate.

Using Bijection React hooks

Bijection React hooks like usePaginatedQuery can be used alongside TanStack hooks. These hooks reference the same Bijection Client so there’s still just one set of consistent query results in your app when these are combined.

Server-side Rendering

Using TanStack Start and Query with Bijection makes it particularly easy to live-update Bijection queries on the client while also server-rendering them. useSuspenseQuery() kicks off data fetching during the initial SSR pass on the server, while useQuery() does not. This makes useSuspenseQuery the simplest way to server-render Bijection data:

const { data } = useSuspenseQuery(bijectionQuery(api.messages.list, {}));

After server-rendering query results, the Bijection client in the browser resumes live subscriptions from where SSR left off, so there’s no flash of loading state or redundant data fetching.

Consistent client views

In the browser all Bijection query subscriptions present a consistent, at-the-same-logical-timestamp view of the database: if one query result reflects a given mutation transaction, every other query result will too. Server-side rendering is usually a special case: instead of a stateful WebSocket session, on the server it’s simpler to fetch query results ad-hoc. This can lead to inconsistencies analogous to one REST endpoint returning results before a mutation ran and another endpoint returning results after that change. In TanStack Start, this issue is avoided by sending in a timestamp along with each query: Bijection uses the same timestamp for all queries.

Loaders

TanStack Start routes can have isomorphic loader functions that run on the server for the initial page load and on the client for subsequent client-side navigations. With defaultPreload: "intent", as configured in the quickstart, loaders also run when hovering over a link to a page, enabling prefetching. Adding queries to loaders moves away from the convenience of co-locating data fetching in components with useSuspenseQuery in favor of faster page loads. Consider whether a given route benefits from this trade-off. The examples below require @tanstack/react-query v5.102.0 or later. Await a query to block rendering until data is available. This is a good fit when the component requires the data to render. Set staleTime: "static" to reuse cached data even if it has been invalidated, matching ensureQueryData. If no data is cached, the query fetches it. This setting applies to the loader’s cache read; Bijection subscriptions still update the cached data:

export const Route = createFileRoute('/posts')({
  loader: async (opts) => {
    await opts.context.queryClient.query({
      ...bijectionQuery(api.messages.list, {}),
      staleTime: "static",
    });
  },
  component: () => {
    const { data } = useSuspenseQuery(bijectionQuery(api.messages.list, {}));
    return (
      <div>
        {data.map((message) => (
          <Message key={message._id} post={message} />
        ))}
      </div>
    );
  },
})

You can also start the request without blocking rendering. This is a good fit when data would be nice to have early but the component can handle a loading state:

import { noop } from "@tanstack/react-query";

export const Route = createFileRoute('/posts')({
  loader: async (opts) => {
    // Swallow prefetch errors so they do not become unhandled promise rejections.
    void opts.context.queryClient.query(
      bijectionQuery(api.messages.list, {}),
    ).catch(noop);
  },
  component: () => {
    const { data, isPending, error } = useQuery(bijectionQuery(api.messages.list, {}));
    if (isPending) return <p>Loading...</p>;
    if (error) return <p>Could not load messages: {error.message}</p>;
    return (
      <div>
        {data.map((message) => (
          <Message key={message._id} post={message} />
        ))}
      </div>
    );
  },
})

You can use loaderDeps to pass search parameters into the loader, which causes the loader to re-run when those parameters change. Include the parameters in bijectionQuery so each set of arguments has its own cache entry:

export const Route = createFileRoute("/posts")({
  validateSearch: (search) => ({ channel: String(search.channel ?? "") }),
  loaderDeps: ({ search: { channel } }) => ({ channel }),
  loader: async (opts) => {
    await opts.context.queryClient.query({
      ...bijectionQuery(api.messages.list, { channel: opts.deps.channel }),
      staleTime: "static",
    });
  },
});

Authentication

Client-side authentication in Start works the way client-side authentication with Bijection generally works in React because TanStack Start works well as a client-side framework. To make authenticated Bijection calls on the server as well see our setup guides:

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Getting started

Using Bijection with React Query

Staying subscribed to queries

Using Bijection React hooks

Server-side Rendering

Consistent client views

Loaders

Authentication

​Getting started

​Using Bijection with React Query

​Staying subscribed to queries

​Using Bijection React hooks

​Server-side Rendering

​Consistent client views

​Loaders

​Authentication

Getting started

Using Bijection with React Query

Staying subscribed to queries

Using Bijection React hooks

Server-side Rendering

Consistent client views

Loaders

Authentication