secondsky/claude-skills / plugins/tanstack-query/skills/tanstack-query
tanstack-query
VerifiedTanStack Query v5 (React Query) server state management. Use for data fetching, caching, mutations, or encountering v4 migration, stale data, invalidation errors.
references/configuration-files.md
View on GitHub# TanStack Query Configuration Files
**Complete configuration templates for TanStack Query v5 projects**
Load this reference when: Setting up project structure, configuring TypeScript, or installing ESLint plugins.
---
## package.json (Full Example)
```json
{
"name": "my-app",
"version": "1.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "tsc && vite build",
"preview": "vite preview"
},
"dependencies": {
"react": "^19.2.0",
"react-dom": "^19.2.0",
"@tanstack/react-query": "^5.101.4"
},
"devDependencies": {
"@tanstack/react-query-devtools": "^5.101.4",
"@tanstack/eslint-plugin-query": "^5.101.4",
"@types/react": "^19.2.0",
"@types/react-dom": "^19.2.0",
"@vitejs/plugin-react": "^5.2.0",
"typescript": "^5.9.3",
"vite": "^7.3.0"
}
}
```
### Why These Versions
**React 19.2.0**
- Required for `useSyncExternalStore` hook used internally by TanStack Query
- Provides concurrent features that Query v5 leverages
**TanStack Query 5.101.4**
- Latest stable version with all v5 fixes
- Includes all breaking change migrations from v4
- Best compatibility with React 19
**DevTools 5.101.4**
- Version-matched to query package
- Tree-shakeable (automatically removed in production builds)
- No manual configuration needed
**TypeScript 5.9.3**
- Best type inference for query hooks
- Improved generic type handling
- Better error messages for query/mutation types
**Vite 7.3.0**
- Fast HMR for development
- Optimized builds with tree-shaking
- Native ES modules support
---
## tsconfig.json (TypeScript Configuration)
```json
{
"compilerOptions": {
"target": "ES2020",
"useDefineForClassFields": true,
"lib": ["ES2020", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
/* Bundler mode */
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"isolatedModules": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true,
/* TanStack Query specific */
"esModuleInterop": true,
"resolveJsonModule": true
},
"include": ["src"]
}
```
### TanStack Query Specific Settings
**Required Settings:**
- `"strict": true` - Enables proper type inference for query data and errors
- `"esModuleInterop": true` - Allows proper imports from TanStack Query
- `"jsx": "react-jsx"` - Uses new JSX transform (React 17+)
**Recommended Settings:**
- `"resolveJsonModule": true` - If loading query keys from JSON files
- `"noUnusedLocals": true` - Catches unused query variables
- `"skipLibCheck": true` - Speeds up builds (TanStack types are well-tested)
**Module Resolution:**
- `"moduleResolution": "bundler"` - Works with Vite/modern bundlers
- `"isolatedModules": true` - Required for Vite HMR
---
## .eslintrc.cjs (ESLint Configuration)
```javascript
module.exports = {
root: true,
env: { browser: true, es2020: true },
extends: [
'eslint:recommended',
'plugin:@typescript-eslint/recommended',
'plugin:react-hooks/recommended',
'plugin:@tanstack/eslint-plugin-query/recommended',
],
ignorePatterns: ['dist', '.eslintrc.cjs'],
parser: '@typescript-eslint/parser',
plugins: ['react-refresh', '@tanstack/query'],
rules: {
'react-refresh/only-export-components': [
'warn',
{ allowConstantExport: true },
],
},
}
```
### ESLint Plugin Benefits
The `@tanstack/eslint-plugin-query` catches:
1. **Query keys as references instead of inline**
```tsx
// ❌ Bad: Query key as variable reference
const key = ['todos']
useQuery({ queryKey: key, queryFn: fetchTodos })
// ✅ Good: Query key inline
useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
```
2. **Missing queryFn**
```tsx
// ❌ Caught by linter
useQuery({ queryKey: ['todos'] })
// ✅ Fixed
useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
```
3. **Using v4 patterns in v5**
```tsx
// ❌ v4 syntax detected
useQuery(['todos'], fetchTodos)
// ✅ v5 syntax
useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
```
4. **Incorrect dependencies in useEffect**
```tsx
// ❌ Missing dependency
const { data } = useQuery(...)
useEffect(() => {
console.log(data)
}, []) // Missing 'data'
// ✅ Correct dependencies
useEffect(() => {
console.log(data)
}, [data])
```
---
## vite.config.ts (Vite Configuration)
```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
optimizeDeps: {
include: ['@tanstack/react-query'],
},
})
```
### Vite Optimization
**optimizeDeps.include**:
- Pre-bundles TanStack Query for faster dev server starts
- Reduces HMR update times
- Prevents re-bundling on every change
---
## Alternative: Bun Setup
For projects using Bun instead of npm:
```bash
# Install dependencies
bun add @tanstack/react-query
bun add -d @tanstack/react-query-devtools @tanstack/eslint-plugin-query
# Run dev server
bun run dev
# Build
bun run build
```
**package.json with Bun:**
```json
{
"scripts": {
"dev": "bun run vite",
"build": "bun run tsc && bun run vite build",
"preview": "bun run vite preview"
}
}
```
---
## Verification Checklist
After setting up configuration files, verify:
- [ ] `npm install` (or `bun install`) succeeds without peer dependency warnings
- [ ] TypeScript compilation succeeds: `tsc --noEmit`
- [ ] ESLint runs without errors: `npm run lint` (if script exists)
- [ ] Dev server starts: `npm run dev`
- [ ] Production build succeeds: `npm run build`
- [ ] DevTools button appears in dev mode (bottom-right corner)
- [ ] No console warnings about missing peer dependencies
---
**Last Updated**: 2026-08-03
**Verified With**: @tanstack/react-query@5.101.4
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |