tanstack-query-best-practices

Files (1)

• SKILL.md

SKILL.md (first lines)

# TanStack Query

Use this skill whenever working with `@tanstack/react-query`.

## Core Principles

Use TanStack Query for **server state**:

- API data
- database-backed data
- remote resources
- cached responses
- asynchronous mutations

Do not use TanStack Query as a replacement for normal React state.

Use React state for temporary client-only state such as:

- open/closed UI
- unsaved form values
- local selections
- temporary interaction state

Before changing query code, inspect:

- installed TanStack Query version
- existing query conventions
- `QueryClient` configuration
- query key conventions
- API/service layer
- TanStack Router integration
- existing `queryOptions` helpers
- mutation/invalidation patterns

Do not force v5 patterns into an older codebase without checking compatibility.

## Queries

Use `useQuery` for reading server data.

Prefer the object syntax:

```tsx
const usersQuery = useQuery({
  queryKey: ["users"],
  queryFn: getUsers,
})
```

The query function should:

- return a Promise
- resolve with the requested data
- throw/reject when the request fails

Do not swallow errors and return fake fallback data unless that is intentional application behavior.

Avoid:

```tsx
useEffect(() => {
  fetchUsers().then(setUsers)
}, [])
```

when the data is server state that TanStack Query should manage.

## Query Keys

Query keys define cache identity.

Every value that changes what data is fetched should normally appear in the query key.

Prefer:

```tsx
useQuery({
  queryKey: ["users", userId],
  queryFn: () => getUser(userId),
})
```

For filtered data:

```tsx
useQuery({
  queryKey: ["users", { page, status }],
  queryFn: () => getUsers({ page, status }),
})
```

Do not use:

```tsx
queryKey: ["users"]
```

when the query function secretly depends on `userId`, `page`, filters, or other changing values.

Query keys must remain serializable and predictable.

Use consistent hierarchical keys:

```tsx
["users"]
["users", "list"]
["users", "list", filters]
["users", "detail", userId]
```

## Reusable Query Definitions

When a query is reused across loaders, components, prefetching, or cache operations, prefer `queryOptions`.

```tsx
export function userQueryOptions(userId: string) {
  return queryOptions({
    queryKey: ["users", "detail", userId],
    queryFn: () => getUser(userId),

From Jack-WebDev/skills, MIT.

More from Jack-WebDev/skills