Skip to content
Esc

@noctcore/eslint-plugin-query

v0.2.06 rules2 recommended4 opt-innamespace noctcore-query

A bad fit for tRPC's classic utils.x.invalidate() integration, where the first rule has nothing to check.

TanStack Query and tRPC cache correctness: invalidations that reach infinite queries, mutation callbacks that survive a remount, handled mutation errors.

The client cache fails in ways that pass type checks and unit tests that mock the client. An invalidation keyed with tRPC’s input-less queryKey() stops reaching a list the day it moves to useInfiniteQuery. A mutate(vars, { onSuccess }) fired from an effect loses its callback when StrictMode or a route change detaches the observer, and the screen waits forever. A mutation with nothing listening for its error fails without anyone noticing.

It will yell at you about tRPC invalidations through an input-less queryKey() (with an autofix to pathKey()) and per-call mutation callbacks inside useEffect, both on in recommended. Mutations with no error handling anywhere is opt-in, because a global MutationCache({ onError }) handles errors where the rule cannot see. Inline query keys (queryKey: ['user', id]) is opt-in too, a convention for codebases that keep keys in a constant or key factory. An exact-key setQueryData(PREFIX, ...) or getQueryData(PREFIX) where the hooks key entries as [...PREFIX, id] is opt-in as well, because the rule reads one file at a time. A queryFn that catches its error and returns a fallback is opt-in too, because returning null for an optional resource is a legitimate contract. It is a bad fit for tRPC’s classic utils.x.invalidate() integration, where the first rule has nothing to check.

Install
npm install --save-dev @noctcore/eslint-plugin-query @typescript-eslint/parser
# or: bun add -D / pnpm add -D @noctcore/eslint-plugin-query @typescript-eslint/parser

The recommended preset enables 2 of 6 rules. The rules board below builds the flat config: start from a preset, switch single rules between error and off, and copy the result.

Each rule links to its page, with the options it takes and Incorrect and Correct examples. A good first read is trpc-invalidate-with-path-key.

2 of 6 at error

--fixsuggestionsneeds optionstype infoEach switch sets a rule to error or off.

effect-fired-mutation-must-bind-callbacks
Require a mutation fired from an effect to carry its onSuccess/onError on useMutation, not as per-call mutate() options, which a detached observer never delivers.
recommended
mutation-requires-error-handling
Require a TanStack Query mutation to handle its error somewhere visible: onError on the hook, onError or a catch at the call, or a read of its error state.
opt-in
prefix-query-key-must-use-set-queries-data
Report setQueryData(PREFIX, ...) and getQueryData(PREFIX) when the file builds its query keys as [...PREFIX, id]: the exact-key call misses every entry, and setQueriesData / getQueriesData match the prefix.
Editor suggestions
opt-in
query-fn-must-not-swallow-error
Disallow a queryFn that catches its error and returns a fallback value, which turns a failed request into cached data the query reports as a success.
opt-in
query-key-must-be-constant
Require query and mutation keys to come from a constant or key factory, not an inline array that starts with a string.
opt-in
trpc-invalidate-with-path-key
Require pathKey() when a tRPC procedure is invalidated, refetched, cancelled, removed or reset without an input. A bare queryKey() misses infinite queries.
Fixable with --fix
recommended