Tanstack

TanStack Query

The core library. Manages async state with caching, background refetching, and stale management.

Setup

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000,    // 5 minutes
      gcTime: 10 * 60 * 1000,      // 10 minutes garbage collection
      retry: 2,
      refetchOnWindowFocus: false,  // Disable for SpacetimeDB (subscriptions handle freshness)
    },
  },
});

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <Router />
    </QueryClientProvider>
  );
}

useQuery

import { useQuery, queryOptions } from "@tanstack/react-query";

// Define query options (reusable, composable)
const usersQueryOptions = queryOptions({
  queryKey: ["users"],
  queryFn: () => fetchUsers(),
  staleTime: 60_000,
});

function UserList() {
  const { data, isLoading, error } = useQuery(usersQueryOptions);

  if (isLoading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <ul>{data.map(user => <li key={user.id}>{user.name}</li>)}</ul>;
}

useMutation

import { useMutation, useQueryClient } from "@tanstack/react-query";

function CreateUserForm() {
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (data: { name: string; email: string }) => createUser(data),
    onSuccess: () => {
      // Invalidate the users query to refetch
      queryClient.invalidateQueries({ queryKey: ["users"] });
    },
    // Or: optimistic update
    onMutate: async (newUser) => {
      await queryClient.cancelQueries({ queryKey: ["users"] });
      const previous = queryClient.getQueryData(["users"]);
      queryClient.setQueryData(["users"], (old: User[]) => [...old, newUser]);
      return { previous };
    },
    onError: (err, newUser, context) => {
      queryClient.setQueryData(["users"], context?.previous);
    },
  });

  return <form onSubmit={(e) => mutation.mutate(formData)}>...</form>;
}

Dependent Queries

const { data: user } = useQuery({
  queryKey: ["user", userId],
  queryFn: () => fetchUser(userId),
});

const { data: orders } = useQuery({
  queryKey: ["orders", user?.id],
  queryFn: () => fetchOrders(user!.id),
  enabled: !!user, // Only runs when user is available
});

Invalidation vs Direct Cache Updates

With SpacetimeDB, prefer setQueryData — the subscription already has the data, no need to refetch.

TanStack Router

Type-safe routing with built-in data loading.

File-Based Routes

src/routes/
├── __root.tsx          # Root layout
├── index.tsx           # /
├── about.tsx           # /about
├── users/
│   ├── index.tsx       # /users
│   └── $userId.tsx     # /users/:userId
└── settings.tsx        # /settings

Route Definition

// src/routes/users/$userId.tsx
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/users/$userId")({
  // Type-safe params
  loader: async ({ params }) => {
    return fetchUser(params.userId); // params.userId is typed as string
  },
  component: UserDetail,
});

function UserDetail() {
  const user = Route.useLoaderData();
  return <h1>{user.name}</h1>;
}

Search Params (Type-Safe)

import { createFileRoute } from "@tanstack/react-router";
import { z } from "zod";

const searchSchema = z.object({
  page: z.number().default(1),
  sort: z.enum(["name", "date"]).default("name"),
  filter: z.string().optional(),
});

export const Route = createFileRoute("/users")({
  validateSearch: searchSchema,
  component: UserList,
});

function UserList() {
  const { page, sort, filter } = Route.useSearch(); // Fully typed
  const navigate = Route.useNavigate();

  return (
    <button onClick={() => navigate({ search: { page: page + 1 } })}>
      Next Page
    </button>
  );
}

Integration with TanStack Query

export const Route = createFileRoute("/users/$userId")({
  loader: async ({ context: { queryClient }, params }) => {
    // Ensure data is loaded before rendering
    return queryClient.ensureQueryData(userQueryOptions(params.userId));
  },
});

Set defaultPreloadStaleTime: 0 in the router to delegate caching to TanStack Query.

TanStack Table

Headless — no UI, just logic. You control all rendering.

Basic Setup

import { useReactTable, getCoreRowModel, createColumnHelper } from "@tanstack/react-table";

type User = { id: number; name: string; email: string; role: string };

const columnHelper = createColumnHelper<User>();

const columns = [
  columnHelper.accessor("name", {
    header: "Name",
    cell: (info) => info.getValue(),
  }),
  columnHelper.accessor("email", {
    header: "Email",
  }),
  columnHelper.accessor("role", {
    header: "Role",
    cell: (info) => <Badge>{info.getValue()}</Badge>,
  }),
  columnHelper.display({
    id: "actions",
    header: "Actions",
    cell: ({ row }) => <button onClick={() => editUser(row.original)}>Edit</button>,
  }),
];

Table Instance

function UserTable({ data }: { data: User[] }) {
  const [sorting, setSorting] = useState<SortingState>([]);
  const [filtering, setFiltering] = useState("");

  const table = useReactTable({
    data,
    columns,
    state: { sorting, globalFilter: filtering },
    onSortingChange: setSorting,
    onGlobalFilterChange: setFiltering,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
  });

  return (
    <table>
      <thead>
        {table.getHeaderGroups().map(headerGroup => (
          <tr key={headerGroup.id}>
            {headerGroup.headers.map(header => (
              <th key={header.id} onClick={header.column.getToggleSortingHandler()}>
                {flexRender(header.column.columnDef.header, header.getContext())}
              </th>
            ))}
          </tr>
        ))}
      </thead>
      <tbody>
        {table.getRowModel().rows.map(row => (
          <tr key={row.id}>
            {row.getVisibleCells().map(cell => (
              <td key={cell.id}>
                {flexRender(cell.column.columnDef.cell, cell.getContext())}
              </td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Anti-pattern: Don't put complex rendering logic inside column definitions. Table is headless — keep column defs focused on data access, handle complex UI in the component.

TanStack Form

Type-safe form state with validation tiers.

Basic Form

import { useForm } from "@tanstack/react-form";
import { z } from "zod";

function CreateUserForm() {
  const form = useForm({
    defaultValues: {
      name: "",
      email: "",
      role: "member" as const,
    },
    onSubmit: async ({ value }) => {
      await createUser(value);
    },
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
      <form.Field
        name="name"
        validators={{
          onChange: z.string().min(2, "Name must be at least 2 characters"),
        }}
      >
        {(field) => (
          <div>
            <input
              value={field.state.value}
              onChange={(e) => field.handleChange(e.target.value)}
              onBlur={field.handleBlur}
            />
            {field.state.meta.errors.map(err => <span key={err}>{err}</span>)}
          </div>
        )}
      </form.Field>

      <form.Subscribe selector={(s) => s.isSubmitting}>
        {(isSubmitting) => (
          <button type="submit" disabled={isSubmitting}>
            {isSubmitting ? "Creating..." : "Create User"}
          </button>
        )}
      </form.Subscribe>
    </form>
  );
}

Validation Tiers

Field Arrays

<form.Field name="tags" mode="array">
  {(field) => (
    <div>
      {field.state.value.map((_, i) => (
        <form.Field key={i} name={`tags[${i}]`}>
          {(subField) => <input value={subField.state.value} onChange={...} />}
        </form.Field>
      ))}
      <button onClick={() => field.pushValue("")}>Add Tag</button>
    </div>
  )}
</form.Field>

SpacetimeDB Integration

Three approaches, from simplest to most flexible:

Option A: SpacetimeDB React Hooks (Simplest)

import { SpacetimeDBProvider, useTable, useReducer } from "spacetimedb/react";

function App() {
  return (
    <SpacetimeDBProvider conn={conn}>
      <UserList />
    </SpacetimeDBProvider>
  );
}

function UserList() {
  const users = useTable(User);       // Reactive, auto-updates
  const createUser = useReducer(conn.reducers.createUser);

  return (
    <ul>
      {users.map(u => <li key={u.id}>{u.name}</li>)}
      <button onClick={() => createUser("New User", "[email protected]")}>Add</button>
    </ul>
  );
}

Pros: Zero boilerplate, no double-caching. Cons: No TanStack Query features (devtools, suspense, error boundaries).

Option B: SpacetimeDB TanStack Bridge (Official)

import { useSpacetimeDBQuery } from "spacetimedb/tanstack";

function UserList() {
  const [users, loading, query] = useSpacetimeDBQuery(User);

  if (loading) return <Spinner />;

  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

Pros: Gets TanStack Query integration (devtools, suspense), official support. Cons: Double-caching (SpacetimeDB cache + TanStack Query cache).

Option C: Custom Bridge (Full Control)

import { useQuery, useQueryClient } from "@tanstack/react-query";

function useSpacetimeTable<T>(table: { all: () => T[]; onInsert: any; onDelete: any; onUpdate: any }, queryKey: string[]) {
  const queryClient = useQueryClient();

  useEffect(() => {
    const unsubs = [
      table.onInsert(() => {
        queryClient.setQueryData(queryKey, () => [...table.all()]);
      }),
      table.onDelete(() => {
        queryClient.setQueryData(queryKey, () => [...table.all()]);
      }),
      table.onUpdate(() => {
        queryClient.setQueryData(queryKey, () => [...table.all()]);
      }),
    ];
    return () => unsubs.forEach(fn => fn());
  }, [table, queryKey, queryClient]);

  return useQuery({
    queryKey,
    queryFn: () => [...table.all()],
    staleTime: Infinity,  // SpacetimeDB pushes updates — never refetch
  });
}

// Usage
function UserList() {
  const { data: users, isLoading } = useSpacetimeTable(User, ["users"]);
  // Full TanStack Query API available: suspense, error boundaries, devtools
}

Pros: Full control, TanStack Query features, custom cache strategy. Cons: More code, you own the bridge.

Which Option?

Double-Caching Warning

SpacetimeDB maintains its own client-side cache of all subscribed rows. TanStack Query adds a second cache layer on top. This means:

• Data exists in two places (memory overhead)
• Cache invalidation must consider both layers
• refetchOnWindowFocus will fight SpacetimeDB's push model

Mitigation: Set staleTime: Infinity and disable refetchOnWindowFocus when using SpacetimeDB subscriptions. Let SpacetimeDB handle freshness.

Bad: Fighting the Subscription Model

// SpacetimeDB already pushes updates — don't also poll
const { data } = useQuery({
  queryKey: ["users"],
  queryFn: () => [...User.all()],
  staleTime: 0,                    // Causes unnecessary re-reads
  refetchOnWindowFocus: true,      // Causes unnecessary re-reads
  refetchInterval: 5000,           // Polling on top of subscriptions
});

Good: Trusting Subscriptions

const { data } = useQuery({
  queryKey: ["users"],
  queryFn: () => [...User.all()],
  staleTime: Infinity,             // SpacetimeDB handles freshness
  refetchOnWindowFocus: false,     // No polling needed
});

// Updates flow through onInsert/onDelete/onUpdate → setQueryData

Best Practices

Common Pitfalls

References

• TanStack Query Docs
• TanStack Router Docs
• TanStack Table Docs
• TanStack Form Docs
• TanStack Start Docs
• SpacetimeDB TanStack Integration