Recipes

jg-tanstack-query

On this page

Patterns for React apps that cache server data with TanStack Query: setting it up, keeping a query across reloads, signing out safely, and a query boundary.

Setting up the client at the root

Create the client and its persister in their own module, so every part of the app shares them:

tsx

import {
  createIndexedDbPersister,
  createQueryClient,
  PersistedQueryProvider,
} from 'jg-tanstack-query';
import type { ReactNode } from 'react';

export const queryClient = createQueryClient();
export const persister = createIndexedDbPersister({
  databaseName: 'app-query-cache',
  storeName: 'queries',
  key: 'query-client',
});

// bump it when a release changes a persisted query's data, so older copies are thrown away
const CACHE_VERSION = 'v3';

export const QueryRoot = ({ children }: { children: ReactNode }) => (
  <PersistedQueryProvider
    client={queryClient}
    persister={persister}
    buster={CACHE_VERSION}
  >
    {children}
  </PersistedQueryProvider>
);

Keeping a query across reloads

Persist what’s public and slow to load, such as a catalog, so the next visit renders it at once and refreshes it in the background:

tsx

import { useQuery } from '@tanstack/react-query';

declare const fetchCatalog: () => Promise<{ id: string; name: string }[]>;

export const Catalog = () => {
  const { data, isPending } = useQuery({
    queryKey: ['catalog'],
    queryFn: fetchCatalog,
    meta: { persist: true },
    staleTime: 60_000,
  });
  if (isPending) {
    return <p>Loading…</p>;
  }
  return (
    <ul>
      {data?.map(({ id, name }) => (
        <li key={id}>{name}</li>
      ))}
    </ul>
  );
};

Leave meta.persist off anything personal, such as an account’s details or messages: it would sit on the disk after the session ends.

Signing out without leaking data

Clear the cache before the next person can use the device, and wait for the clear before showing the sign-in page:

tsx

import { clearQueryCache, createIndexedDbPersister, createQueryClient } from 'jg-tanstack-query';

declare const queryClient: ReturnType<typeof createQueryClient>;
declare const persister: ReturnType<typeof createIndexedDbPersister>;
declare const endSession: () => Promise<void>;
declare const navigate: (path: string) => void;

export const SignOutButton = () => {
  const signOut = async (): Promise<void> => {
    await endSession();
    await clearQueryCache(queryClient, persister);
    navigate('/sign-in');
  };
  return (
    <button
      type="button"
      onClick={() => void signOut()}
    >
      Sign out
    </button>
  );
};

When sign-out happens right after the page loads, the clear waits for the persisted copy to finish restoring, so restored data can’t come back afterwards.

A query boundary component

useQueryBoundary decides and draws nothing, so one small component gives every screen the same loader, error, and load-more control, in the app’s own markup:

tsx

import type { ReactNode } from 'react';
import { type IQueryBoundaryQuery, useQueryBoundary } from 'jg-tanstack-query';

type IQueryBoundaryProps = {
  queries: IQueryBoundaryQuery[];
  resolutionKey: string;
  children: ReactNode;
};

export const QueryBoundary = ({ queries, resolutionKey, children }: IQueryBoundaryProps) => {
  const boundary = useQueryBoundary({ queries, resolutionKey });
  return (
    <>
      {boundary.isLoaderVisible ? <p role="status">Loading…</p> : null}
      {boundary.hasError ? (
        <div
          role="alert"
          data-presentation={boundary.errorPresentation}
        >
          Something went wrong.
          <button
            type="button"
            onClick={() => void boundary.retryFailed()}
          >
            Retry
          </button>
        </div>
      ) : null}
      {boundary.canRenderContent ? children : null}
      {boundary.loadMoreQuery === undefined ? null : (
        <button
          type="button"
          onClick={() => void boundary.loadMoreQuery?.fetchNextPage?.()}
        >
          Load more
        </button>
      )}
    </>
  );
};

A blocking error replaces the content, so it deserves the space the content would take; a retained one sits beside content that’s still current, so a compact notice fits. Pass an isAccessDenied that recognizes the API’s 403 code, so content the user lost access to disappears at once.