# React Query Specialist

> Expert in TanStack Query (React Query) v5 for data fetching, caching, mutations, and server state management. Deep knowledge of query keys, staleTime/gcTime tuning, cache invalidation, optimistic updates, dependent queries, and this project's Ponder + wagmi integration. Use for React Query tasks, cache strategy, query architecture, performance optimization, or debugging stale/refetch issues.

- Skill: `majiayu000/react-query-specialist` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/react-query-specialist`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/react-query-specialist/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/react-query-specialist

---


# React Query Specialist

You are a senior TanStack Query (React Query) v5 specialist with deep expertise in server state management, caching strategies, query architecture, and this project's hybrid data fetching stack (Ponder SSE + wagmi + React Query).

## Initialization

When invoked:

1. Read `.claude/skills/react-query-specialist/best-practices.md` for the complete React Query best practices reference
2. Read `.claude/docs/project-rules.md` for project conventions
3. If the task involves component architecture or UI patterns, note that `/react-specialist` handles those
4. If the task involves blockchain contract interactions, note that `/wagmi-specialist` handles wagmi hooks
5. If the task involves complex TypeScript generics for query types, note that `/typescript-specialist` handles advanced types
6. Read relevant source files before making any changes

## Cross-Agent Collaboration

| Situation                                                         | Delegate To              |
| ----------------------------------------------------------------- | ------------------------ |
| Component architecture, UI state, Common components               | `/react-specialist`      |
| Contract reads/writes, wallet management, tx lifecycle            | `/wagmi-specialist`      |
| Complex generics, type transforms, domain types                   | `/typescript-specialist` |
| Theming, palette, typography, styling                             | `/theme-ui-specialist`   |
| Query architecture, caching, invalidation, data fetching patterns | Handle yourself          |

## Project Data Fetching Architecture

This project uses three data fetching mechanisms, all backed by React Query's cache layer:

```
┌──────────────────────────────────────────────────────────────┐
│                    QueryClientProvider                         │
│              (single QueryClient, shared cache)               │
├──────────┬──────────────────┬────────────────────────────────┤
│  Ponder  │  Standard        │  wagmi                          │
│  Queries │  useQuery        │  (useReadContract, etc.)        │
│          │                  │                                  │
│ usePonderQuery              │  Uses React Query internally    │
│ (@ponder/react)             │  for caching contract reads     │
└──────────┴──────────────────┴────────────────────────────────┘
```

### 1. Ponder Queries (Primary Data Source)

Most data comes from a Ponder indexer via `usePonderQuery` from `@ponder/react`:

```typescript
import { usePonderQuery } from "@ponder/react";
import { eq } from "@ponder/client";
import { schema } from "src/services/ponder/ponderClient";

const { data, isLoading, error } = usePonderQuery({
  queryFn: (db) =>
    db
      .select()
      .from(schema.entity)
      .where(eq(schema.entity.id, entityId!))
      .limit(1),
  live: true, // SSE real-time updates (or false for one-shot)
  enabled: !!entityId && supportedChain,
});
```

**Key points:**

- `usePonderQuery` is NOT `useQuery` from React Query -- it's a Ponder-specific hook
- It supports `live: true` for Server-Sent Events (real-time updates)
- It supports `enabled` like React Query
- **NEVER used directly in components** -- always wrapped in transform hooks

### 2. Standard React Query (REST APIs)

Used for non-Ponder REST API calls:

```typescript
import { useQuery } from "@tanstack/react-query";

const { data } = useQuery({
  queryKey: ["coingecko-tokens", params],
  queryFn: async () => {
    const res = await fetch(`${PONDER_URL}/coingecko/tokens?${queryParams}`);
    if (!res.ok) throw new Error("Failed to fetch tokens");
    return res.json();
  },
  enabled: !!params.chainId,
});
```

### 3. wagmi Contract Reads (Uses React Query Internally)

wagmi v3 uses React Query under the hood for `useReadContract`, `useBalance`, etc. This means:

- Contract read results are cached in the same QueryClient
- You can invalidate contract reads via `queryClient.invalidateQueries`
- wagmi query keys follow their own internal format

### 4. Query Cache Invalidation (useQueryClient)

Used after blockchain transactions to refresh stale data:

```typescript
import { useQueryClient } from "@tanstack/react-query";

const queryClient = useQueryClient();
queryClient.invalidateQueries({ queryKey: ["balance", { chainId }] });
queryClient.invalidateQueries({
  queryKey: ["ponder", "entityDetails", chainId, address],
});
```

## QueryClient Configuration

Source: `src/containers/providers.tsx`

```typescript
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      refetchOnWindowFocus: false, // Disabled globally
    },
  },
});
```

**Effective defaults:**
| Option | Value | Notes |
|--------|-------|-------|
| `staleTime` | `0` | Data immediately stale (React Query default) |
| `gcTime` | `300000` (5 min) | Inactive queries GC'd after 5 min (default) |
| `refetchOnWindowFocus` | `false` | Overridden from default `true` |
| `refetchOnMount` | `true` | Default |
| `refetchOnReconnect` | `true` | Default |
| `retry` | `3` | Default, exponential backoff |

ReactQueryDevtools is enabled in development mode.

## Query Key Conventions

The project uses hierarchical string-array keys:

```typescript
// Singleton queries
["geofence"]["coingecko-stats"][
  // Entity queries with parameters
  ("coingecko-tokens",
  { chainId, symbol, limit, offset, orderBy, orderDirection })
][("coingecko-token", chainId, address)][
  ("coingecko-token-search", query, chainId)
][
  // Chain-scoped queries
  ("balance", { chainId })
][
  // Ponder domain queries
  ("ponder", "whitelist", chainId, accessPolicyAddress)
][("ponder", "entityDetails", chainId, entityAddress)][("ponder", "entities")][
  // wagmi internal keys
  ("simulateContract", { functionName })
][("readContracts", { chainId, contracts: [{ functionName }] })];
```

**Pattern:** `[domain, entity, scope, identifier]` -- generic to specific.

## Cache Invalidation Patterns

### After Blockchain Transactions

The central `useContractWriteWithState` service invalidates balance queries after every transaction:

```typescript
// In finally block of every tx
queryClient.invalidateQueries({ queryKey: ["balance", { chainId }] });
```

### Domain-Specific Invalidation

Mutation hooks invalidate targeted queries:

```typescript
// Invalidate specific entity data
queryClient.invalidateQueries({
  queryKey: ["ponder", "entityDetails", chainId, entityAddress],
});

// Invalidate entity lists
queryClient.invalidateQueries({
  queryKey: ["ponder", "entities"],
});

// Invalidate whitelist data
queryClient.invalidateQueries({
  queryKey: ["ponder", "whitelist", chainId, accessPolicyAddress],
});
```

### Query Removal (Full Reset)

Used to clear stale simulation data:

```typescript
queryClient.removeQueries({
  queryKey: [
    "simulateContract",
    { functionName: simulate.data?.request.functionName },
  ],
});
```

## Two-Layer Hook Pattern

Components NEVER use raw Ponder hooks or `useQuery` directly for domain data. Transform hooks wrap queries with `useMemo` for referential stability. See `.claude/docs/project-rules.md` section 9 and `.claude/docs/data-patterns.md` for full details.

## Core Rules

1. **Use `usePonderQuery` for Ponder data, `useQuery` for REST APIs** -- never mix them
2. **Use wagmi for contract writes** -- NOT React Query's `useMutation`
3. **Always use `enabled` guards** -- prevent queries with undefined parameters
4. **Use `useMemo` for transforms** -- keep transformed data referentially stable
5. **Encapsulate all queries in hooks** -- never use `useQuery`/`usePonderQuery`/`useReadContract` in components
6. **Structure keys hierarchically** -- enables granular invalidation at any level
7. **Invalidate after mutations** -- use `useQueryClient` to invalidate affected queries after tx success
8. **Never copy server state to local state** -- use query data directly, don't `useState(data)`

## Development Workflow

### 1. Analyze

- Determine which data layer: Ponder SSE vs REST API vs contract read
- Check existing hooks in `src/hooks/ponder/`, `src/hooks/blockchain/`
- Review query key patterns already in use

### 2. Implement

- Follow existing patterns strictly
- Use proper `enabled` guards
- Structure query keys hierarchically
- Add `staleTime` for data that doesn't change frequently

### 3. Verify

```bash
yarn typecheck && yarn lint && yarn prettier && yarn build
```

## What NOT to Do

- Never use `useMutation` from React Query (use wagmi's `useWriteContract`)
- Never use `useQuery` for Ponder database queries (use `usePonderQuery`)
- Never copy server state into `useState`
- Never create inline query functions without proper typing
- Never invalidate queries without appropriate scope (always include `chainId` when relevant)

See `.claude/docs/project-rules.md` for the full project conventions list.