Skip to content
Skills Library
Programming · Learning & explanation

TanStack Types

/TanStack Types

This skill should be used when the user asks about "type-safe React Query", "queryOptions typing", "Zod validation", "TypeScript with TanStack Query", "generic useQuery", "DataTag", "infer query types", or needs guidance on type safety patterns, runtime validation, and TypeScript best practices for TanStack Query.

Repository
brain-dump ↗
Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

This skill should be used when the user asks about "type-safe React Query", "queryOptions typing", "Zod validation", "TypeScript with TanStack Query", "generic useQuery", "DataTag", "infer query types", or needs guidance on type safety patterns, runtime validation, and TypeScript best practices for TanStack Query.

Triggers from the description

type-safe React QueryqueryOptions typingZod validationTypeScript with TanStack Querygeneric useQueryDataTaginfer query types
Original author description

This skill should be used when the user asks about "type-safe React Query", "queryOptions typing", "Zod validation", "TypeScript with TanStack Query", "generic useQuery", "DataTag", "infer query types", or needs guidance on type safety patterns, runtime validation, and TypeScript best practices for TanStack Query.

How it works

  1. Core Principle: Trust in Types
  2. The Anti-Pattern: Manual Generics
  3. The Pattern: Type the Data Source
  4. The queryOptions Helper
  5. Runtime Validation with Zod
  6. Query Factories with Full Type Safety
  7. Typing Selectors
  8. Typing Mutations
  9. Error Types
  10. Quick Reference
Original SKILL.md headings · 349 lines, 1,138 words
SKILL.md preview
---
name: TanStack Types
description: This skill should be used when the user asks about "type-safe React Query", "queryOptions typing", "Zod validation", "TypeScript with TanStack Query", "generic useQuery", "DataTag", "infer query types", or needs guidance on type safety patterns, runtime validation, and TypeScript best practices for TanStack Query.
version: 1.0.0
---

# TanStack Query Type Safety Patterns

This skill provides guidance for achieving type safety in TanStack Query, covering queryOptions, runtime validation with Zod, and TypeScript best practices based on TKDodo's recommendations.

## Core Principle: Trust in Types

The foundation of type safety is **trust in type definitions**. Without trust, TypeScript becomes just a linter that can be silenced.

> "To truly leverage the power of TypeScript, there is one thing that you need above all: Trust."

## The Anti-Pattern: Manual Generics

Avoid passing type parameters directly to `useQuery`:

```typescript
// BAD: Manual generics
const { data } = useQuery<Todo>({
  queryKey: ['todos', id],
  queryFn: () => fetchTodo(id),
})
// data is Todo | undefined, but is it really?
// The generic is just a type assertion in disguise
```

This violates the "golden rule of generics": **For a generic to be useful, it must appear at least twice.**

## The Pattern: Type the Data Source

Instead of typing the consumer, type the source:

```typescript
// GOOD: Type the queryFn return
const fetchTodo = async (id: string): Promise<Todo> => {
  const response = await axios.get(`/todos/${id}`)
  return response.data
}

// Types flow through automatically
const { data } = useQuery({
  queryKey: ['todos', id],
  queryFn: () => fetchTodo(id),
})
// data is Todo | undefined, and we can trust it
```

## The queryOptions Helper

The `queryOptions()` helper provides compile-time type safety:

```typescript
import { queryOptions, useQuery } from '@tanstack/react-query'

const todoQueryOptions = (id: string) => queryOptions({
  queryKey: ['todos', id] as const,
  queryFn: async (): Promise<Todo> => {
    const response = await api.get(`/todos/${id}`)
    return response.data
  },
  staleTime: 5 * 60 * 1000,
})

// Usage - types are inferred correctly
const { data } = useQuery(todoQueryOptions(id))
// data: Todo | undefined

// TypeScript catches property typos
const bad = queryOptions({
  queryKey: ['todos'],
  queryFn: fetchTodos,
  stallTime: 5000, // Error! Did you mean 'staleTime'?
})
```

### DataTag for getQueryData/setQueryData

queryOptions enables type-safe cache access:

```typescript
const options = todoQueryOptions(id)

// getQueryData knows the return type
const cachedTodo = queryClient.getQueryData(options.queryKey)
// cachedTodo: Todo | undefined

// setQueryData gets type checking
queryClient.setQueryData(options.queryKey, (old) => {
  // old: Todo | undefined
  return old ? { ...old, completed: true } : old
})
```

## Runtime Validation with Zod

The network boundary is inherently untrustworthy. Validate responses at runtime:

```typescript
import { z } from 'zod'

// Define schema
const todoSchema = z.object({
  id: z.string(),
  title: z.string(),
  completed: z.boolean(),
  createdAt: z.string().datetime(),
})

type Todo = z.infer<typeof todoSchema>

// Validate in queryFn
const fetchTodo = async (id: string): Promise<Todo> => {
  const response = await axios.get(`/todos/${id}`)
  return todoSchema.parse(response.data) // Throws if invalid
}
```

### Benefits of Runtime Validation

1. **Catches mismatches early**: API changes are caught immediately
2. **Descriptive errors**: Zod provides clear error messages
3. **Triggers error state**: Invalid data triggers React Query's error handling
4. **Self-documenting**: Schema serves as documentation

### List Validation

```typescript
const todosSchema = z.array(todoSchema)

const fetchTodos = async (): Promise<Todo[]> => {
  const response = await axios.get('/todos')
  return todosSchema.parse(response.data)
}
```

### Partial/Optional Fields

```typescript
const todoSchema = z.object({
  id: z.string(),
  title: z.string(),
  description: z.string().optional(),
  metadata: z.record(z.string()).nullable(),
})
```

## Query Factories with Full Type Safety

Combine queryOptions with factory pattern:

```typescript
// queries/todos.ts
import { queryOptions } from '@tanstack/react-query'
import { z } from 'zod'

const todoSchema = z.object({
  id: z.string(),
  title: z.string(),
  completed: z.boolean(),
})

const todosSchema = z.array(todoSchema)

export type Todo = z.infer<typeof todoSchema>

export const todoQueries = {
  all: () => queryOptions({
    queryKey: ['todos'] as const,
    queryFn: async () => {
      const res = await api.get('/todos')
      return todosSchema.parse(res.data)
    },
  }),

  detail: (id: string) => queryOptions({
    queryKey: ['todos', 'detail', id] as const,
    queryFn: async () => {
      const res = await api.get(`/todos/${id}`)
      return todoSchema.parse(res.data)
    },
    staleTime: 5 * 60 * 1000,
  }),

  byStatus: (status: 'active' | 'completed') => queryOptions({
    queryKey: ['todos', 'status', status] as const,
    queryFn: async () => {
      const res = await api.get(`/todos?status=${status}`)
      return todosSchema.parse(res.data)
    },
  }),
}
```

## Typing Selectors

When using `select`, type the output properly:

```typescript
// Basic select - output type inferred
const { data: title } = useQuery({
  ...todoQueryOptions(id),
  select: (data) => data.title, // data: Todo, returns string
})
// title: string | undefined

// With generic for reusable options
const productOptions = <TData = Product>(
  id: string,
  select?: (data: Product) => TData
) => queryOptions({
  queryKey: ['products', id] as const,
  queryFn: () => fetchProduct(id),
  select,
})

// Usage
const { data: product } = useQuery(productOptions(id))
// product: Product | undefined

const { data: title } = useQuery(productOptions(id, (p) => p.title))
// title: string | undefined
```

## Typing Mutations

Apply the same patterns to mutations:

```typescript
const createTodoSchema = z.object({
  title: z.string().min(1),
  description: z.string().optional(),
})

type CreateTodoInput = z.infer<typeof createTodoSchema>

const useCreateTodo = () => {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (input: CreateTodoInput) => {
      // Validate input
      const validated = createTodoSchema.parse(input)
      const res = await api.post('/todos', validated)
      return todoSchema.parse(res.data)
    },
    onSuccess: (newTodo) => {
      // newTodo is typed as Todo
      queryClient.setQueryData(
        todoQueries.detail(newTodo.id).queryKey,
        newTodo
      )
    },
  })
}
```

## Error Types

Type your errors for better error handling:

```typescript
// Define error types
interface ApiError {
  code: string
  message: string
  details?: Record<string, string[]>
}

const apiErrorSchema = z.object({
  code: z.string(),
  message: z.string(),
  details: z.record(z.array(z.string())).optional(),
})

// Parse errors in fetch wrapper
const apiFetch = async <T>(
  url: string,
  schema: z.ZodType<T>
): Promise<T> => {
  const response = await fetch(url)

  if (!response.ok) {
    const error = await response.json()
    throw apiErrorSchema.parse(error)
  }

  return schema.parse(await response.json())
}

// Usage in query
const { data, error } = useQuery({
  queryKey: ['todos'],
  queryFn: () => apiFetch('/todos', todosSchema),
})
// error: ApiError | null
```

## Quick Reference

| Goal | Pattern |
|------|---------|
| Type query data | Type the queryFn return, not useQuery generic |
| Catch typos | Use queryOptions() helper |
| Type-safe cache access | Use queryOptions with getQueryData/setQueryData |
| Runtime validation | Parse with Zod in queryFn |
| Reusable queries | Query factories with queryOptions |
| Typed selectors | Generic parameter on factory function |

## Common Mistakes

### 1. Using Generics as Type Assertions

```typescript
// BAD: This is lying to TypeScript
const { data } = useQuery<Todo>({
  queryKey: ['todo'],
  queryFn: () => fetch('/todo').then(r => r.json()),
})
// data could be anything at runtime!

// GOOD: Validate at runtime
const { data } = useQuery({
  queryKey: ['todo'],
  queryFn: () => fetch('/todo').then(r => r.json()).then(todoSchema.parse),
})
```

### 2. Not Using `as const` for Query Keys

```typescript
// BAD: Types are too wide
queryKey: ['todos', id] // string[]

// GOOD: Exact types preserved
queryKey: ['todos', id] as const // readonly ['todos', string]
```

## Additional Resources

### Reference Files

For detailed patterns and advanced techniques, consult:
- **`references/advanced-typing.md`** - Complex type scenarios

### Related Skills

- **tanstack-query** - Core concepts, query factories
- **tanstack-mutations** - Type-safe mutations
- **tanstack-errors** - Typed error handling
Files in this package (2)
  • SKILL.md 9 KB
  • references/advanced-typing.md 9 KB

Versions

The database has no other skills named TanStack Types.

Database snapshot: 13.11.2026 · package version f47deac19772 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90TanStack Query Core
    This skill should be used when the user asks about "TanStack Query", "React Query", "useQuery", "query keys", "staleTime", "query client setup", "query factories", "queryOptions", or needs guidance on core TanStack Query concepts, mental models, and setup patterns.
  • 90TanStack Errors
    This skill should be used when the user asks about "React Query error handling", "error boundaries with useQuery", "throwOnError", "global error callbacks", "onError callback", "query error state", "mutation error handling", or needs guidance on error handling strategies and…
  • 100react-query-best-practices
    React Query v4 (TanStack Query) best practices, patterns, and troubleshooting. Use when working with useQuery, useMutation, query invalidation, caching, WebSocket integration, or any async state management in React. Based on TkDodo's comprehensive blog series.
  • 100tanstack-query
    Best practices for TanStack Query v5 (React Query) server state management, including query key factories, the queryOptions helper, mutations, optimistic updates, infinite queries, and Suspense mode. Use when fetching or caching server data in React, writing custom…
  • 95typescript-idioms
    TypeScript strict typing: type narrowing, discriminated unions, Zod runtime validation, generic utility types, and Vitest testing. Use when writing or refactoring TypeScript across frontend, backend, or full-stack projects.
  • 100tanstack-query
    TanStack Query v5 performance optimization for data fetching, caching, mutations, and query patterns. This skill should be used when using useQuery, useMutation, queryClient, prefetch patterns, or TanStack Query caching. This skill does NOT cover generating query hooks from…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.