Skip to main content
TanStack Query comes with its own ESLint plugin. This plugin is used to enforce best practices and to help you avoid common mistakes when using the library.

​
Installation

The plugin is a separate package that you need to install: 
npm i -D @tanstack/eslint-plugin-query

​
Flat Config (eslint.config.js)

To enable all of the recommended rules for our plugin, add the following config:
eslint.config.js
import pluginQuery from '@tanstack/eslint-plugin-query'

export default [
  ...pluginQuery.configs['flat/recommended'],
  // Any other config...
]
This will enable all recommended rules with sensible defaults.

​
Custom Setup

Alternatively, you can load the plugin and configure only the rules you want to use:
eslint.config.js
import pluginQuery from '@tanstack/eslint-plugin-query'

export default [
  {
    plugins: {
      '@tanstack/query': pluginQuery,
    },
    rules: {
      '@tanstack/query/exhaustive-deps': 'error',
      '@tanstack/query/stable-query-client': 'error',
    },
  },
  // Any other config...
]

​
Legacy Config (.eslintrc)

To enable all of the recommended rules for our plugin, add plugin:@tanstack/query/recommended in extends:
.eslintrc
{
  "extends": ["plugin:@tanstack/query/recommended"]
}

​
Custom Setup

Alternatively, add @tanstack/query to the plugins section, and configure the rules you want to use:
.eslintrc
{
  "plugins": ["@tanstack/query"],
  "rules": {
    "@tanstack/query/exhaustive-deps": "error",
    "@tanstack/query/stable-query-client": "error"
  }
}

​
Available Rules

The ESLint plugin includes the following rules:

exhaustive-deps

Ensures all variables used in queryFn are included in the query key

no-rest-destructuring

Prevents rest destructuring in query results to maintain render optimization

stable-query-client

Ensures QueryClient is created outside of component render

no-unstable-deps

Prevents unstable values in query keys that could cause infinite loops

infinite-query-property-order

Enforces correct property order for infinite queries

no-void-query-fn

Ensures query functions return a value, not void

mutation-property-order

Enforces consistent property order in mutation options

​
Rule Attributes

Rules may have the following attributes:
  • ✅ Recommended: Enabled in the recommended configuration
  • 🔧 Fixable: Can be automatically fixed with eslint --fix

​
Why Use the ESLint Plugin?

The ESLint plugin helps you avoid common pitfalls:

​
1. Query Key Consistency

One of the most common mistakes is forgetting to include all variables in the query key: 
// ❌ Bad: todoId not in query key
useQuery({
  queryKey: ['todos'],
  queryFn: () => fetchTodo(todoId),
})

// ✅ Good: all variables in query key
useQuery({
  queryKey: ['todos', todoId],
  queryFn: () => fetchTodo(todoId),
})
Without proper query keys, queries may not be cached independently or refetched when variables change.

​
2. QueryClient Stability

Creating a new QueryClient on every render is a common mistake: 
// ❌ Bad: new client on every render
function App() {
  const queryClient = new QueryClient()
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}

// ✅ Good: stable client instance
const queryClient = new QueryClient()
function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}

​
3. Render Optimization

The plugin helps maintain TanStack Query’s smart render optimization by preventing patterns that break it.

​
Configuration Tips

Start with the recommended configuration and adjust rules based on your team’s needs. The recommended config represents battle-tested best practices.

​
Adjusting Rule Severity

You can adjust the severity of any rule: 
rules: {
  '@tanstack/query/exhaustive-deps': 'warn', // warn instead of error
  '@tanstack/query/stable-query-client': 'error',
}

​
Disabling Rules

If you need to disable a rule for a specific line: 
// eslint-disable-next-line @tanstack/query/exhaustive-deps
useQuery({
  queryKey: ['todos'],
  queryFn: () => fetchTodo(todoId),
})
Only disable rules when you have a good reason. The rules are designed to prevent bugs.

​
Migration from v4

If you’re upgrading from TanStack Query v4:
  • The prefer-query-object-syntax rule has been removed (object syntax is now required)
  • All other rules remain compatible

​
Next Steps

Exhaustive Deps Rule

Learn about the exhaustive-deps rule in detail

Stable Query Client Rule

Understand the stable-query-client rule

Build docs developers (and LLMs) love

Get started for freeTalk to us