tanstack-query
/tanstack-query
TanStack Query (formerly React Query) fetches, caches and updates server data in React apps, replacing hand-written useEffect + useState fetching. Use it when the user wants caching, background refetching, mutations with optimistic updates, infinite scroll, Suspense or Next.js server prefetching with v5 hooks such as useQuery, useMutation and useInfiniteQuery.
- Author
- TerminalSkills ↗
- Repository
- skills ↗
- Licence
- Apache-2.0
- Last repository change
- 25.10.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
TanStack Query (formerly React Query) fetches, caches and updates server data in React apps, replacing hand-written useEffect + useState fetching. Use it when the user wants caching, background refetching, mutations with optimistic updates, infinite scroll, Suspense or Next.js server prefetching with v5 hooks such as useQuery, useMutation and useInfiniteQuery.
Original author description
TanStack Query (formerly React Query) fetches, caches and updates server data in React apps, replacing hand-written useEffect + useState fetching. Use it when the user wants caching, background refetching, mutations with optimistic updates, infinite scroll, Suspense or Next.js server prefetching with v5 hooks such as useQuery, useMutation and useInfiniteQuery.
How it works
- Overview
- Instructions
- Examples
- Guidelines
SKILL.md preview
---
name: tanstack-query
description: >-
TanStack Query (formerly React Query) fetches, caches and updates server
data in React apps, replacing hand-written useEffect + useState fetching.
Use it when the user wants caching, background refetching, mutations with
optimistic updates, infinite scroll, Suspense or Next.js server prefetching
with v5 hooks such as useQuery, useMutation and useInfiniteQuery.
license: Apache-2.0
compatibility: React 18+, @tanstack/react-query v5, TypeScript 4.7+
metadata:
author: terminal-skills
version: 1.1.0
repository: https://github.com/TanStack/query
category: development
tags: "react, data-fetching, cache, state-management, async"
---
# TanStack Query
## Overview
TanStack Query (v5, package `@tanstack/react-query`) manages server state: it caches responses by query key, dedupes requests, refetches in the background and gives mutations a lifecycle for optimistic UI. It needs React 18 or newer. These examples use the v5 object-only API; v4 names (`cacheTime`, `isLoading` as "no data yet", `keepPreviousData`, `onSuccess` on `useQuery`) no longer exist.
## Instructions
### Setup
```bash
npm install @tanstack/react-query
npm install -D @tanstack/react-query-devtools
```
```tsx
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 60_000, // fresh for 1 min; default is 0 (always stale)
gcTime: 10 * 60_000, // unused cache kept 10 min; default is 5 min
},
},
});
export function App() {
return (
<QueryClientProvider client={queryClient}>
<Dashboard />
<ReactQueryDevtools initialIsOpen={false} />
</QueryClientProvider>
);
}
```
Devtools are left out of production builds automatically.
### Queries
`fetch` does not reject on HTTP 4xx/5xx, so throw yourself or the query ends up "successful" with an error body.
```tsx
import { useQuery } from "@tanstack/react-query";
type User = { id: number; name: string };
async function fetchUsers(): Promise<User[]> {
const res = await fetch("/api/users");
if (!res.ok) throw new Error(`Users request failed: ${res.status}`);
return res.json();
}
function UserList() {
const { data, isPending, isError, error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
});
if (isPending) return <p>Loading...</p>;
if (isError) return <p>{error.message}</p>; // error is Error by default in v5
return <ul>{data.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
}
```
In v5, `isPending` means "no data yet"; `isLoading` is `isPending && isFetching` (first fetch in flight). Only `isPending` narrows `data` to defined.
Share key and function with `queryOptions` so `useQuery`, `useSuspenseQuery`, `prefetchQuery` and `setQueryData` stay in sync and typed:
```tsx
import { queryOptions, useQuery } from "@tanstack/react-query";
export const userQuery = (id: number) =>
queryOptions({
queryKey: ["users", id],
queryFn: () => fetch(`/api/users/${id}`).then((r) => r.json() as Promise<User>),
staleTime: 30_000,
});
const { data } = useQuery({ ...userQuery(7), select: (u) => u.name });
```
Dependent query: `useQuery({ ...projectsQuery(userId!), enabled: userId != null })`.
### Mutations and optimistic updates
```tsx
import { useMutation, useQueryClient } from "@tanstack/react-query";
type Todo = { id: number | string; title: string; completed: boolean };
export function useCreateTodo() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: async (newTodo: { title: string }) => {
const res = await fetch("/api/todos", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(newTodo),
});
if (!res.ok) throw new Error(`Create failed: ${res.status}`);
return (await res.json()) as Todo;
},
onMutate: async (newTodo) => {
await queryClient.cancelQueries({ queryKey: ["todos"] });
const previous = queryClient.getQueryData<Todo[]>(["todos"]);
queryClient.setQueryData<Todo[]>(["todos"], (old = []) => [
...old,
{ id: `temp-${Date.now()}`, completed: false, ...newTodo },
]);
return { previous };
},
onError: (_err, _vars, context) => {
queryClient.setQueryData(["todos"], context?.previous);
},
// return the promise so the mutation stays pending until the refetch ends
onSettled: () => queryClient.invalidateQueries({ queryKey: ["todos"] }),
});
}
```
Simpler alternative with no cache writes: render `mutation.variables` as a greyed item while `mutation.isPending`; it disappears on its own after the refetch. From another component use `useMutationState` with a `mutationKey`.
### Infinite queries
`initialPageParam` is required in v5. `maxPages` only works together with both `getNextPageParam` and `getPreviousPageParam`. Returning `undefined` or `null` from `getNextPageParam` means there is no next page.
```tsx
import { useInfiniteQuery } from "@tanstack/react-query";
type FeedPage = { items: { id: number; text: string }[]; nextCursor: string | null; prevCursor: string | null };
function InfiniteFeed() {
const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
queryKey: ["feed"],
queryFn: async ({ pageParam }): Promise<FeedPage> => {
const res = await fetch(`/api/feed?cursor=${encodeURIComponent(pageParam)}`);
if (!res.ok) throw new Error(`Feed failed: ${res.status}`);
return res.json();
},
initialPageParam: "",
getNextPageParam: (lastPage) => lastPage.nextCursor,
getPreviousPageParam: (firstPage) => firstPage.prevCursor, // required with maxPages
maxPages: 5, // optional: keep at most 5 pages in memory
});
return (
<>
{data?.pages.flatMap((p) => p.items).map((i) => <p key={i.id}>{i.text}</p>)}
<button onClick={() => fetchNextPage()} disabled={!hasNextPage || isFetchingNextPage}>
{isFetchingNextPage ? "Loading..." : hasNextPage ? "Load more" : "No more"}
</button>
</>
);
}
```
### Suspense, pagination and Next.js
- `useSuspenseQuery` never returns `data` as undefined; wrap it in `<Suspense>` and an error boundary. It has no `enabled` option.
- For page-number pagination keep the old page visible with `placeholderData: keepPreviousData` (imported from the package; replaces the removed `keepPreviousData: true`).
- Next.js App Router: create the client in a `"use client"` providers file and reuse one client in the browser (new client per request on the server); set `staleTime` above 0 so hydrated data is not refetched at once. Prefetch in a Server Component and hand it over:
```tsx
// app/posts/page.tsx
import { dehydrate, HydrationBoundary } from "@tanstack/react-query";
import { getQueryClient } from "../get-query-client"; // your per-request factory
import Posts from "./posts"; // client component calling useQuery({ queryKey: ["posts"], ... })
export default async function PostsPage() {
const queryClient = getQueryClient();
await queryClient.prefetchQuery({ queryKey: ["posts"], queryFn: getPosts });
return (
<HydrationBoundary state={dehydrate(queryClient)}>
<Posts />
</HydrationBoundary>
);
}
```
## Examples
**"Show a list of users and refetch when I add one."** Use the `UserList` query above plus a mutation whose `onSuccess` returns `queryClient.invalidateQueries({ queryKey: ["users"] })`. The list refetches in the background; `isFetching` is true meanwhile while `data` stays on screen.
**"Make the todo checkbox update instantly and roll back if the server fails."** Use `useCreateTodo`'s pattern with `setQueryData` in `onMutate`, the snapshot in the returned context, rollback in `onError` and `invalidateQueries` in `onSettled`. In the browser the checkbox flips at once; on a 500 it flips back.
**"Infinite scroll for a feed."** Use `InfiniteFeed`; trigger `fetchNextPage` from a button or an IntersectionObserver. With `maxPages: 5`, pages beyond the window are dropped and refetched when you scroll back.
## Guidelines
- Query keys are arrays; put every variable the function uses in them (`["users", userId, { status }]`). `invalidateQueries({ queryKey: ["users"] })` matches by prefix.
- `staleTime` decides when a mounted query refetches (default 0); `gcTime` decides how long unused data stays cached (default 5 min). `staleTime: "static"` also blocks manual invalidation; use `Infinity` when you still want invalidation to work.
- v5 removed `onSuccess`, `onError` and `onSettled` from `useQuery`; run side effects in `useEffect`, or in a `QueryCache` callback (`new QueryClient({ queryCache: new QueryCache({ onError }) })`). Mutation callbacks still exist.
- Do not copy query data into `useState`; read it from the hook and derive values with `select`.
- Retries are 3 on the client with exponential backoff and none on the server. Set `retry: false` in tests.
- Not a fit for purely client-side state (modals, form drafts); use component state or a store.
Files in this package (2)
- SKILL.md 9 KB
- _scores.json 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · TerminalSkills/skills | 100 | Apache-2.0 |
| zenobi-us/dotfiles | 100 | MIT |
| claude-dev-suite/claude-dev-suite | 100 | MIT |
| kriscard/Skills | 100 | MIT |
| Mindrally/skills | 100 | Apache-2.0 |
| pproenca/dot-skills | 100 | MIT |
| secondsky/claude-skills | 91 | MIT |
Database snapshot: 13.11.2026 · package version b5da0b474f78 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100tanstack-query-next-actions
TanStack Query v5 in Next.js 15 App Router — QueryClient + QueryClientProvider setup, prefetch in RSC + HydrationBoundary, mutations with optimistic updates, Server Actions interop, invalidation patterns, infinite queries, suspense queries, devtools. Use when you need rich… - 100rn-data-fetching
Use when fetching data from APIs in React Native: choosing between fetch+useEffect (didactic only) and TanStack Query (production default), wiring the QueryClient provider, building queries / mutations / optimistic updates / paginated and infinite lists / cache invalidation /… - 90TanStack Query
Expert guidance for TanStack Query (React Query) including queries, mutations, caching, invalidation, optimistic updates, pagination, and infinite queries. Use this when managing server state in React applications. - 95tanstack-query-best-practices
TanStack Query (React Query) best practices for data fetching, caching, mutations, and server state management. Activate when building data-driven React applications with server state. - 100nextjs-tanstack-query
Use when implementing client-side data fetching, server prefetching with hydration, or optimistic mutations in Next.js 16 with TanStack Query. - 100tanstack-query-expert
TanStack Query (React Query) expertise: data fetching, stale time, mutations, optimistic updates, Next.js SSR. Use for async state management.