# 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 as a script file and run:

## 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: 和 Redux 冲突吗？**
A: 不。Redux 管 client state，Query 管 server state。组合使用。

**Q: staleTime 和 gcTime 区别？**
A: `staleTime` 决定数据多久变为 stale（触发后台 refetch）；`gcTime` 决定未订阅数据多久从 cache 删除。

**Q: 支持 SSR 吗？**
A: 支持。用 `HydrationBoundary` + `dehydrate` 在服务端预取。

## 来源与致谢 Sources

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

---
Source: https://tokrepo.com/en/workflows/26726f79-355f-11f1-9bc6-00163e2b0d79
Author: Script Depot