# TanStack Query — Async State & Data Fetching for the Web

> TanStack Query (formerly React Query) is a powerful asynchronous state management library for TS/JS that handles server-state, caching, background updates, and data synchronization across React, Solid, Svelte, and Vue.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
npm i @tanstack/react-query
```

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

const qc = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={qc}>
      <Todos />
    </QueryClientProvider>
  );
}

function Todos() {
  const { data, isLoading } = useQuery({
    queryKey: ["todos"],
    queryFn: () => fetch("/api/todos").then(r => r.json()),
  });
  if (isLoading) return <p>Loading...</p>;
  return <ul>{data.map(t => <li key={t.id}>{t.title}</li>)}</ul>;
}
```

## Intro

TanStack Query (formerly React Query) is the missing data-fetching library for web applications. It eliminates manual state management for server data (loading/error/caching/refetch).

- **Repo**: https://github.com/TanStack/query
- **Stars**: 49K+
- **Adapters**: React, Solid, Svelte, Vue, Angular
- **License**: MIT

## What TanStack Query Does

- **Caching** — automatic with configurable `staleTime`/`gcTime`
- **Deduping** — identical requests collapsed
- **Background refetch** — on window focus, reconnect, interval
- **Pagination/Infinite queries** — first-class support
- **Mutations** — optimistic updates with rollback
- **Devtools** — inspect cache state in real time

## Architecture

Singleton `QueryClient` holds the cache. Each `useQuery` subscribes via `queryKey`. Cache invalidation uses key prefix matching: `queryClient.invalidateQueries({ queryKey: ["todos"] })`.

## Self-Hosting

No backend. Client-only library. Install via package manager.

## Key Features

- Framework-agnostic core
- Typed queries (infer from queryFn)
- Optimistic updates
- Parallel & dependent queries
- Prefetching & SSR support (Next.js, Remix, Nuxt)
- Offline support
- Automatic retries with exponential backoff

## Comparison

| Library | Scope | Mutations | Caching |
|---|---|---|---|
| TanStack Query | Server state | Yes | Automatic |
| SWR | Server state | Limited | Automatic |
| Redux Toolkit Query | Server state | Yes | Manual tags |
| Apollo Client | GraphQL | Yes | Normalized |

## FAQ

**Q: Does it conflict with Redux?**
A: No. Redux manages client state; Query manages server state. Use them together.

**Q: What's the difference between staleTime and gcTime?**
A: `staleTime` determines how long before data becomes stale (triggering a background refetch); `gcTime` determines how long unsubscribed data stays in the cache before being removed.

**Q: Does it support SSR?**
A: Yes. Use `HydrationBoundary` + `dehydrate` to prefetch on the server.

## Sources & Credits

- Docs: https://tanstack.com/query
- GitHub: https://github.com/TanStack/query
- License: MIT

---
Source: https://tokrepo.com/en/workflows/tanstack-query-async-state-data-fetching-web-26726f79
Author: Script Depot