0
# @tanstack/eslint-plugin-query
1
2
@tanstack/eslint-plugin-query is an ESLint plugin specifically designed for TanStack Query applications. It provides a comprehensive set of linting rules to enforce best practices and prevent common pitfalls when using TanStack Query, helping developers avoid runtime errors and maintain consistent coding patterns.
3
4
## Package Information
5
6
- **Package Name**: @tanstack/eslint-plugin-query
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tanstack/eslint-plugin-query`
10
11
## Core Imports
12
13
```typescript
14
import queryPlugin from "@tanstack/eslint-plugin-query";
15
// Named exports also available:
16
import { Plugin } from "@tanstack/eslint-plugin-query";
17
```
18
19
For legacy configuration:
20
21
```javascript
22
const queryPlugin = require("@tanstack/eslint-plugin-query");
23
```
24
25
## Basic Usage
26
27
### Modern Flat Config (ESLint 9+)
28
29
```javascript
30
import queryPlugin from "@tanstack/eslint-plugin-query";
31
32
export default [
33
// Other configs...
34
...queryPlugin.configs["flat/recommended"]
35
];
36
```
37
38
### Legacy Config (ESLint 8)
39
40
```javascript
41
module.exports = {
42
plugins: ["@tanstack/query"],
43
extends: ["plugin:@tanstack/query/recommended"],
44
// Or configure individual rules:
45
rules: {
46
"@tanstack/query/exhaustive-deps": "error",
47
"@tanstack/query/no-rest-destructuring": "warn",
48
"@tanstack/query/stable-query-client": "error",
49
}
50
};
51
```
52
53
## Capabilities
54
55
### Plugin Structure
56
57
Main plugin object with rules and configurations.
58
59
```typescript { .api }
60
interface Plugin extends Omit<ESLint.Plugin, 'rules'> {
61
rules: Record<RuleKey, RuleModule<any, any, any>>;
62
configs: {
63
recommended: ESLint.ConfigData;
64
'flat/recommended': Array<Linter.Config>;
65
};
66
}
67
68
const plugin: Plugin;
69
export default plugin;
70
```
71
72
### Configuration Presets
73
74
Pre-configured rule sets for immediate use.
75
76
```typescript { .api }
77
// Legacy configuration format
78
interface RecommendedConfig {
79
plugins: string[];
80
rules: {
81
'@tanstack/query/exhaustive-deps': 'error';
82
'@tanstack/query/no-rest-destructuring': 'warn';
83
'@tanstack/query/stable-query-client': 'error';
84
'@tanstack/query/no-unstable-deps': 'error';
85
'@tanstack/query/infinite-query-property-order': 'error';
86
'@tanstack/query/no-void-query-fn': 'error';
87
'@tanstack/query/mutation-property-order': 'error';
88
};
89
}
90
91
// Modern flat configuration format
92
interface FlatRecommendedConfig extends Array<{
93
name: string;
94
plugins: Record<string, Plugin>;
95
rules: Record<string, string>;
96
}> {}
97
```
98
99
### ESLint Rules
100
101
Collection of seven specialized linting rules for TanStack Query applications.
102
103
#### Exhaustive Dependencies Rule
104
105
Ensures all dependencies used in queryFn are included in queryKey to prevent stale closure issues.
106
107
```typescript { .api }
108
// Rule: @tanstack/query/exhaustive-deps
109
// Severity: error
110
// Description: Exhaustive deps rule for useQuery
111
// Provides auto-fix suggestions for missing dependencies
112
```
113
114
**Usage Example:**
115
```typescript
116
// ❌ Bad - missing dependencies in queryKey
117
useQuery({
118
queryKey: ['user'],
119
queryFn: () => fetchUser(userId, settings), // userId and settings not in queryKey
120
});
121
122
// ✅ Good - all dependencies included
123
useQuery({
124
queryKey: ['user', userId, settings],
125
queryFn: () => fetchUser(userId, settings),
126
});
127
```
128
129
#### No Rest Destructuring Rule
130
131
Disallows rest destructuring in queries to prevent excessive re-renders.
132
133
```typescript { .api }
134
// Rule: @tanstack/query/no-rest-destructuring
135
// Severity: warn
136
// Description: Disallows rest destructuring in queries
137
```
138
139
**Usage Example:**
140
```typescript
141
// ❌ Bad - rest destructuring can cause issues
142
const { data, ...rest } = useQuery({ queryKey: ['user'], queryFn: fetchUser });
143
144
// ✅ Good - explicit destructuring
145
const { data, isLoading, error } = useQuery({ queryKey: ['user'], queryFn: fetchUser });
146
```
147
148
#### Stable Query Client Rule
149
150
Makes sure that QueryClient is stable to prevent unnecessary re-renders.
151
152
```typescript { .api }
153
// Rule: @tanstack/query/stable-query-client
154
// Severity: error
155
// Description: Makes sure that QueryClient is stable
156
```
157
158
**Usage Example:**
159
```typescript
160
// ❌ Bad - creating new QueryClient instance on each render
161
function App() {
162
return (
163
<QueryClientProvider client={new QueryClient()}>
164
<MyComponent />
165
</QueryClientProvider>
166
);
167
}
168
169
// ✅ Good - stable QueryClient instance
170
const queryClient = new QueryClient();
171
function App() {
172
return (
173
<QueryClientProvider client={queryClient}>
174
<MyComponent />
175
</QueryClientProvider>
176
);
177
}
178
```
179
180
#### No Unstable Dependencies Rule
181
182
Disallows putting the result of query hooks directly in a React hook dependency array to prevent infinite re-render loops.
183
184
```typescript { .api }
185
// Rule: @tanstack/query/no-unstable-deps
186
// Severity: error
187
// Description: Disallow putting the result of query hooks directly in a React hook dependency array
188
```
189
190
**Usage Example:**
191
```typescript
192
// ❌ Bad - using query result directly in dependency array
193
const { data: user } = useQuery({ queryKey: ['user'], queryFn: fetchUser });
194
useEffect(() => {
195
console.log('User changed');
196
}, [user]); // This causes infinite re-renders
197
198
// ✅ Good - use specific properties or data content
199
useEffect(() => {
200
console.log('User changed');
201
}, [user?.id]); // Only re-run when user ID changes
202
```
203
204
#### Infinite Query Property Order Rule
205
206
Ensures correct order of inference sensitive properties for infinite queries.
207
208
```typescript { .api }
209
// Rule: @tanstack/query/infinite-query-property-order
210
// Severity: error
211
// Description: Ensure correct order of inference sensitive properties for infinite queries
212
```
213
214
**Usage Example:**
215
```typescript
216
// ✅ Good - properties in correct order
217
useInfiniteQuery({
218
queryKey: ['posts'],
219
queryFn: fetchPosts,
220
initialPageParam: 0,
221
getNextPageParam: (lastPage) => lastPage.nextCursor,
222
});
223
```
224
225
#### No Void Query Function Rule
226
227
Ensures queryFn returns a non-undefined value to prevent runtime issues.
228
229
```typescript { .api }
230
// Rule: @tanstack/query/no-void-query-fn
231
// Severity: error
232
// Description: Ensures queryFn returns a non-undefined value
233
```
234
235
**Usage Example:**
236
```typescript
237
// ❌ Bad - query function returns void
238
useQuery({
239
queryKey: ['user'],
240
queryFn: () => { console.log('fetching'); }, // returns void
241
});
242
243
// ✅ Good - query function returns data
244
useQuery({
245
queryKey: ['user'],
246
queryFn: () => fetchUser(), // returns Promise<User>
247
});
248
```
249
250
#### Mutation Property Order Rule
251
252
Ensures correct order of inference-sensitive properties in useMutation().
253
254
```typescript { .api }
255
// Rule: @tanstack/query/mutation-property-order
256
// Severity: error
257
// Description: Ensure correct order of inference-sensitive properties in useMutation()
258
```
259
260
**Usage Example:**
261
```typescript
262
// ✅ Good - properties in correct order
263
useMutation({
264
mutationFn: updateUser,
265
onSuccess: (data) => {
266
queryClient.invalidateQueries({ queryKey: ['user'] });
267
},
268
onError: (error) => {
269
console.error('Update failed:', error);
270
},
271
});
272
```
273
274
## Types
275
276
```typescript { .api }
277
import type { ESLint, Linter } from 'eslint';
278
import type { RuleModule } from '@typescript-eslint/utils/ts-eslint';
279
280
type RuleKey = keyof typeof rules;
281
282
interface Plugin extends Omit<ESLint.Plugin, 'rules'> {
283
rules: Record<RuleKey, RuleModule<any, any, any>>;
284
configs: {
285
recommended: ESLint.ConfigData;
286
'flat/recommended': Array<Linter.Config>;
287
};
288
}
289
290
type ExtraRuleDocs = {
291
recommended: 'strict' | 'error' | 'warn';
292
}
293
```
294
295
## Framework Compatibility
296
297
This ESLint plugin works with all TanStack Query framework adapters and automatically detects the correct query hooks from:
298
299
- **React**: `@tanstack/react-query`
300
- **Vue**: `@tanstack/vue-query`
301
- **Solid**: `@tanstack/solid-query`
302
- **Svelte**: `@tanstack/svelte-query`
303
- **Angular**: `@tanstack/angular-query-experimental`
304
305
The plugin uses intelligent import detection and only applies rules to code that uses TanStack Query hooks.
306
307
## Error Handling
308
309
The plugin automatically detects TanStack Query imports and only applies rules to relevant code. Rules provide detailed error messages and auto-fix suggestions where possible. If you encounter false positives, ensure your TanStack Query imports follow standard patterns:
310
311
```typescript
312
// Supported import patterns
313
import { useQuery } from '@tanstack/react-query';
314
import { useQuery } from '@tanstack/vue-query';
315
import { useQuery } from '@tanstack/solid-query';
316
import { useQuery } from '@tanstack/svelte-query';
317
```
318
319
## TypeScript Integration
320
321
The plugin includes full TypeScript definitions and integrates seamlessly with TypeScript ESLint parser. When using TypeScript, the plugin can provide enhanced type-aware linting for improved accuracy.