web/.agents/skills/tanstack-query-best-practices/rules/query-cancellation.md
TanStack Query provides an AbortSignal to cancel in-flight requests when queries become stale or components unmount. Pass this signal to your fetch calls to prevent memory leaks and wasted bandwidth.
// Not using abort signal - requests complete even when unnecessary
const { data } = useQuery({
queryKey: ['search', searchTerm],
queryFn: async () => {
// User types fast: "a", "ab", "abc"
// Three requests fire, all complete, wasting bandwidth
const response = await fetch(`/api/search?q=${searchTerm}`)
return response.json()
},
})
// Component unmounts but request keeps running
function UserProfile({ userId }: { userId: string }) {
const { data } = useQuery({
queryKey: ['user', userId],
queryFn: async () => {
const response = await fetch(`/api/users/${userId}`)
return response.json() // Completes even if user navigated away
},
})
}
const { data } = useQuery({
queryKey: ['search', searchTerm],
queryFn: async ({ signal }) => {
const response = await fetch(`/api/search?q=${searchTerm}`, {
signal, // Pass abort signal to fetch
})
return response.json()
},
})
// Now when user types "a", "ab", "abc" quickly:
// - "a" request is cancelled when "ab" starts
// - "ab" request is cancelled when "abc" starts
// - Only "abc" completes
import axios from 'axios'
const { data } = useQuery({
queryKey: ['users', userId],
queryFn: async ({ signal }) => {
const response = await axios.get(`/api/users/${userId}`, {
signal, // Axios supports AbortSignal
})
return response.data
},
})
function SearchResults() {
const queryClient = useQueryClient()
const [searchTerm, setSearchTerm] = useState('')
const { data } = useQuery({
queryKey: ['search', searchTerm],
queryFn: async ({ signal }) => {
const response = await fetch(`/api/search?q=${searchTerm}`, { signal })
return response.json()
},
enabled: searchTerm.length > 0,
})
// Cancel all search queries manually
const handleClear = () => {
queryClient.cancelQueries({ queryKey: ['search'] })
setSearchTerm('')
}
return (
<div>
<input
value={searchTerm}
onChange={(e) => setSearchTerm(e.target.value)}
/>
<button onClick={handleClear}>Clear</button>
<Results data={data} />
</div>
)
}
const updateTodo = useMutation({
mutationFn: (todo: Todo) => api.updateTodo(todo),
onMutate: async (newTodo) => {
// Cancel outgoing queries to prevent overwriting optimistic update
await queryClient.cancelQueries({ queryKey: ['todos'] })
await queryClient.cancelQueries({ queryKey: ['todos', newTodo.id] })
// Proceed with optimistic update...
const previousTodos = queryClient.getQueryData(['todos'])
queryClient.setQueryData(['todos'], (old) => /* ... */)
return { previousTodos }
},
})
// For non-fetch APIs that need custom cancellation
const { data } = useQuery({
queryKey: ['expensive-computation', params],
queryFn: ({ signal }) => {
return new Promise((resolve, reject) => {
// Check if already cancelled
if (signal.aborted) {
reject(new DOMException('Aborted', 'AbortError'))
return
}
const worker = new Worker('computation.js')
worker.postMessage(params)
worker.onmessage = (e) => resolve(e.data)
worker.onerror = (e) => reject(e)
// Listen for cancellation
signal.addEventListener('abort', () => {
worker.terminate()
reject(new DOMException('Aborted', 'AbortError'))
})
})
},
})
| Scenario | Cancelled? |
|---|---|
| Query key changes | Yes |
| Component unmounts | Yes |
queryClient.cancelQueries() called | Yes |
| Refetch triggered | Previous request cancelled |
enabled becomes false | Yes |
signal to fetch/axios for automatic cancellationonError - they're silently droppedqueryClient.cancelQueries() before optimistic updates