Glossary

TanStack

TanStack is an umbrella for several headless, predominantly TypeScript-oriented projects that can be used independently. The best-known TanStack Query manages asynchronous server state on a client, while Router, Table, Virtual, Form and Start have different responsibilities.

Short definition

A shared ecosystem rather than one universal package.

The projects share an emphasis on headless APIs, type safety and keeping logic separate from visual presentation. An application can use Query alone for data, Table alone for a data grid, or Router without adopting the other parts.

TanStack does not replace JavaScript, TypeScript or React. Its libraries run inside frontend applications, and framework support differs by project; the current support matrix must be checked for each specific library.

Problem it solves

Specialised application logic without prescribing a visual system.

TanStack projects focus on complex, recurring parts of frontend infrastructure. An application retains its own components and design while avoiding a new implementation of server-data caching, type-safe routing or a table model.

fetching, caching, synchronising and updating server data in a browser
type-safe navigation and nested routes for client applications
headless tables with sorting, filtering, pagination and custom rendering
virtualising long lists and grids by rendering only a visible portion
form state, validation and submission without a prescribed design
full-stack React or Solid applications built over TanStack Router with TanStack Start

Practical example

An order detail loaded with TanStack Query

A query key identifies the order data in the client cache. The queryFn calls an existing REST API, and the component receives a pending, error or data state. staleTime determines how long data is considered fresh; it is not a promise that the value is absolutely current.

After a successful order status update, the mutation invalidates the matching query. This marks it stale, and an active observer may refetch it. A production implementation would also handle authentication, HTTP error mapping, request cancellation and any optimistic update.

TypeScript / React

const orderQuery = useQuery({
  queryKey: ['orders', orderId],
  queryFn: () => fetchOrder(orderId),
  staleTime: 30_000,
})

const changeStatus = useMutation({
  mutationFn: (status: OrderStatus) => updateOrderStatus(orderId, status),
  onSuccess: () => queryClient.invalidateQueries({
    queryKey: ['orders', orderId],
  }),
})

How TanStack Query works

Query key → cache → query function → server → data → component.

The flow shows the most common use of one part of the ecosystem. It says nothing about a database query language or the internal backend implementation.

Query key A stable, serialisable key identifies data, such as an order list with a particular filter.
Client cache QueryClient tracks data, freshness, observing components and request state. This cache belongs to the client, not the backend.
Query function An asynchronous function gets data from an API or another Promise-based source and must reject its Promise for an error.
Interface states The component responds to pending, error and success and can distinguish the initial load from a background refetch.
Mutation It creates, changes or deletes remote data. It cannot automatically infer which queries became outdated.
Invalidation and refetch The application invalidates precise keys according to the actual change, updates the cache from the response or allows data to refetch.

Main current projects

Each library addresses a different application layer.

The official catalogue evolves and also includes further specialised and newer projects. The following independent parts are particularly relevant to common frontend work.

TanStack Query

Fetches, caches and synchronises asynchronous server state. It provides queries, mutations, invalidation, retry and background refetch; it is not a database query language.

TanStack Router

A client router for React and Solid with type-safe navigation, nested routes, loaders and search parameters. It is not the server-side HTTP router of a backend.

TanStack Table

Headless table and data-grid logic. It models columns, rows, sorting and filtering, but the application provides markup, styles and accessibility.

TanStack Virtual

Headless virtualisation for long lists, grids and scrollable elements. It reduces the number of rendered DOM nodes, not the amount of data fetched from a server automatically.

TanStack Form

Form state and validation with TypeScript and multi-framework support. It cannot replace server-side validation of untrusted input.

TanStack Start

A full-stack framework built over TanStack Router for React and Solid, with SSR, server functions and related runtime tools. Its status and hosting adapters should be checked for the exact version.

Limitations and common mistakes

A capable client cache still needs a precise data contract.

Where it can help

standardising loading, error and repeated-request states
sharing server data between components through an identical query key
keeping table or router logic separate from a particular UI
carrying types between routes, search parameters and components

Risks and common mistakes

using Query as a global store for every piece of local UI state
invalidating overly broad keys or forgetting dependent views
assuming that a client cache always contains the newest server value
hiding an unsuitable backend contract behind complex client transformations
adopting several TanStack libraries merely because they share a brand

Practical use and comparison

Server state is not the same as local interface state.

Server state originates from a remote source, can change without the current client knowing, is asynchronous and is often shared with other users. Whether a dialog is open, a section expanded or an unsaved field being edited is local UI state. TanStack Query focuses on the first group; local state can remain in a component or a specialised store.

TanStack Query does not replace an API, REST or GraphQL. Its queryFn merely calls the selected asynchronous source. It does not change the server data model, authorisation, rate limiting or backend cache, and a query key is not automatically sent to a database.

A client cache speeds up repeated use of previously fetched values and manages their lifecycle for that application. It cannot guarantee that a server value has not changed. staleTime, focus or reconnect events, polling and targeted invalidation determine when values can refetch; a useful configuration follows business tolerance for stale data.

A mutation represents an asynchronous operation with a side effect. On success, the application can write the server response into one cache entry or invalidate every query the change affects. An optimistic update can make the interface feel faster but needs a rollback or another meaningful response when the server rejects it.

TanStack Router controls navigation within a client or full-stack web application. A server router still receives HTTP requests on the backend. TanStack Table similarly does not provide a finished visual table, and Virtual does not fetch data in pages automatically; the application must design those boundaries.

In a single-page application with several shared API views, Query can greatly simplify synchronisation. A small page with one request may be clearer with a framework loader or plain fetch. The richer library fits when its cache, lifecycle and observability address a recurring problem.

Implementation checks

Treat keys, freshness and error states as part of the data contract.

A sound integration follows how frequently the data changes and how much delay the interface can tolerate rather than accepting every default blindly.

include every variable used by the query function in its query key
invalidate only the views actually affected by a mutation and handle request races
distinguish the initial pending state, background refetch, empty data and an error
validate an untrusted API response and do not mistake TypeScript for runtime validation
check framework support, version and maturity for each TanStack project independently

Frequently asked questions

TanStack and server data in practice

Is TanStack one library or framework?

No. It is an ecosystem of independent libraries and tools. TanStack Start is a full-stack framework, while Query, Table and Virtual are separate projects.

Is TanStack Query a database query language?

No. Query here means asynchronous loading of server data on a client. The actual database query remains on the backend.

Does TanStack Query replace REST or GraphQL?

No. It works over a Promise-based function that can call REST, GraphQL or another source. It does not alter the API contract or server implementation.

Should an open dialog be stored in TanStack Query?

Usually not. An open dialog is local UI state, while Query manages remote asynchronous data shared with a server.

Does the client cache guarantee current data?

No. Freshness depends on server changes, staleTime, invalidation, refetch rules and any real-time signals.

Personal experience

Frontend data needs a lifecycle as explicit as its backend API.

When building web applications I connect client state, error scenarios and caching to the actual server contract.

View my skills Discuss a project