Queries and cache utilities

Call finite client-exposed routes with native TanStack Query types.

Call a backend operation from React using the contract generated from your application’s routes.

Query finite routes

useRoute, useInfiniteRoute, useSuspenseRoute, and useRouteUtils accept only finite exposed routes. Inputs, outputs, errors, selection, page parameters, signals, and query options are inferred from generated declarations.

The Hello route generates GET /hello. Import useRoute and useRelkitClient from @relkit/client/react, then render this component under the provider from the Frontend guide:

/** Displays the typed Hello result after the provider resolves backend identity.
 * @returns Loading, connection failure, request failure, or the successful greeting. */
export function Greeting() {
  const { status } = useRelkitClient();
  const greeting = useRoute("GET /hello", { input: { name: "RELKIT" } });

  if (status === "application-updated") {
    return <p role="alert">The API changed. Pull its contract and restart the frontend.</p>;
  }
  if (status === "error") return <p role="alert">Cannot connect to the API.</p>;
  if (greeting.isError) return <p role="alert">{greeting.error.message}</p>;
  if (greeting.isPending) return <p role="status">Loading greeting…</p>;
  return <h1>{greeting.data.message}</h1>;
}

The input and data.message follow the backend’s schemas. An invalid selector or input fails typechecking after the generated declarations are included. GET /hello is the procedure selector; the client still uses RPC rather than constructing a REST request.

Choose query helpers

API	Use it when
`useRoute`	The component renders loading, error, and success states.
`useSuspenseRoute`	A ready provider and your Suspense/error boundaries own loading and failure. It throws while the provider is not ready.
`useInfiniteRoute`	The backend already accepts pagination input; supply `initialPageParam`, `input(page)`, and `getNextPageParam`. It does not add backend pagination.
`useRouteUtils`	You need the selected procedure’s underlying query/mutation option builders.
`createTanstackQueryUtils`	An application outside the RELKIT React hooks owns its QueryClient and identity lifecycle. Import it from `@relkit/client/tanstack-query`.

For the standalone query adapter, install its selected peers in the caller package:

From this guide’s application/package root, install only its selected requirements:

bun add @opentelemetry/api@1.9.1 @orpc/tanstack-query@2.0.0-beta.31 @relkit/client@0.8.2 '@tanstack/query-core@>=5.80.2'

Keep these owner-specific versions and the lockfile together. Runtime SDKs belong in dependencies; build/type tooling belongs in devDependencies. Installing an adapter does not supply its optional SDK peers or enable the feature’s configuration.

The React installation already includes these peers. Its managed hooks use identity-scoped relkitKey keys. The underlying option builders do not automatically produce those keys: use a managed query’s refetch() for a simple refresh, or preserve the full provider scope when interacting with its cache. See server rendering for the same requirement when prefetching.

Keep streams separate

Routes with streaming output are deliberately absent from these selectors. Use useStream instead. Routes marked client: false have neither a route-ID RPC procedure nor a URL alias.

Reference and source