# Tanstack Query Intent Core Tune Defaults Freshness Retr 58e4e7c9

> Use this when configuring staleTime, gcTime, cache lifetime, retry, retryDelay, refetchOnWindowFocus, refetchOnReconnect, refetchInterval, networkMode, focusManager, onlineManager, timeoutManager, or QueryClient defaultOptions.

- Skill: `lukasa1993/tanstack-query-intent-core-tune-defaults-freshness-retr-58e4` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lukasa1993/tanstack-query-intent-core-tune-defaults-freshness-retr-58e4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lukasa1993/tanstack-query-intent-core-tune-defaults-freshness-retr-58e4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: lukasa1993 (https://skillmd.com/u/lukasa1993)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lukasa1993/tanstack-query-intent-core-tune-defaults-freshness-retr-58e4

---


## Setup

```ts
import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60_000,
      gcTime: 10 * 60_000,
      retry: 2,
      refetchOnWindowFocus: true,
    },
  },
})
```

## Core Patterns

### Set freshness close to the data source

```ts
import { queryOptions } from '@tanstack/react-query'

export const settingsOptions = queryOptions({
  queryKey: ['settings'],
  queryFn: async () => ({ theme: 'system' }),
  staleTime: 5 * 60_000,
})
```

### Disable retries in tests

```ts
import { QueryClient } from '@tanstack/react-query'

export function createTestQueryClient() {
  return new QueryClient({
    defaultOptions: { queries: { retry: false } },
  })
}
```

### Use networkMode deliberately

```ts
import { queryOptions } from '@tanstack/react-query'

export const metricsOptions = queryOptions({
  queryKey: ['metrics'],
  queryFn: async () => ({ count: 1 }),
  networkMode: 'online',
})
```

## Common Mistakes

### HIGH Confusing gcTime with freshness

Wrong:

```ts
import { useQuery } from '@tanstack/react-query'

export function useProfile() {
  return useQuery({
    queryKey: ['profile'],
    queryFn: async () => ({ name: 'Tanner' }),
    gcTime: 60_000,
  })
}
```

Correct:

```ts
import { useQuery } from '@tanstack/react-query'

export function useProfile() {
  return useQuery({
    queryKey: ['profile'],
    queryFn: async () => ({ name: 'Tanner' }),
    staleTime: 60_000,
  })
}
```

`gcTime` controls unused cache retention; `staleTime` controls whether cached data is considered fresh.

Source: TanStack/query:docs/framework/react/guides/important-defaults.md

### HIGH static staleTime blocks invalidation expectations

Wrong:

```ts
import { useQuery } from '@tanstack/react-query'

export function useTodos() {
  return useQuery({
    queryKey: ['todos'],
    queryFn: async () => [{ id: 1 }],
    staleTime: 'static',
  })
}
```

Correct:

```ts
import { useQuery } from '@tanstack/react-query'

export function useTodos() {
  return useQuery({
    queryKey: ['todos'],
    queryFn: async () => [{ id: 1 }],
    staleTime: 60_000,
  })
}
```

`staleTime: 'static'` opts out of refetching even when the query is invalidated.

Source: TanStack/query:docs/framework/react/guides/important-defaults.md

### HIGH Tests hang on retries

Wrong:

```ts
import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient()
```

Correct:

```ts
import { QueryClient } from '@tanstack/react-query'

export const queryClient = new QueryClient({
  defaultOptions: { queries: { retry: false } },
})
```

Default retries add delay and can make failing tests wait before surfacing errors.

Source: TanStack/query:docs/framework/react/guides/testing.md

See also: `compositions/persist-offline-and-restore-caches` for persistence rules that depend on gcTime and networkMode.