TanStack Best Practices for React

Comprehensive patterns for TanStack Query, TanStack Router, and their integration. Each section is organized by priority so you can focus on what matters most first.

In this codebase (BMS stack)

Before hand-writing fetch/query/table code, check whether these apply — they replace the generic patterns below for the endpoints/UI they cover:

• Data fetching: if the backend publishes an OpenAPI schema (FastAPI, Kull.GenericBackend, …), use the generated SDK + generated TanStack Query options (src/lib/generated/@tanstack/react-query.gen.ts, from @hey-api/openapi-ts) instead of hand-writing queryFns and query keys — see openapi-typed-client. Everything under Query Keys below still applies, but only for endpoints without a generated client (e.g. a third-party API).

• Tables: use @bmsuisse/datagrid's <DataGrid> instead of useReactTable for any list/table UI — see ui-components. Wire its server mode to a query the same way as any other paginated fetch:

  import { useState } from 'react'
  import { DataGrid, type GridState } from '@bmsuisse/datagrid'
  import { useQuery } from '@tanstack/react-query'