Query keys and invalidation analysis

Make query identity explicit#

Use a factory such as:

import { queryOptions } from '@tanstack/react-query'

export function speakerOptions(slug: string) {
  return queryOptions({
    queryKey: ['speaker', slug],
    queryFn: async () => ({ slug, name: 'Example speaker' }),
  })
}

Open Query Keys and find the indexed key/function. slug is part of the identity because the result depends on it. A key omitting it can cause separate requests to share a cache identity unintentionally.

Inspect duplicate keys#

Create a second options factory with the same key but a different result shape. Query Graph can surface duplicate keys and function fingerprints. Review whether the duplication is intentional reuse or a collision; shared keys are not inherently wrong when the data contract is the same.

Follow invalidation edges#

A mutation updating a speaker often needs to invalidate the related query:

await queryClient.invalidateQueries({ queryKey: ['speaker', slug] })

Inspect the corresponding mutation and edge in Query Graph. Missing-invalidation findings identify recognized writes without recognized invalidation; custom cache update strategies or wrappers may need manual review. Static analysis cannot decide the complete caching policy.

Review a change#

Navigate from a key/edge back to source, inspect the query’s variables, and rerun application tests after adjusting identity or invalidation. A warning disappearing is not enough: verify that data refreshes for the intended entity without invalidating unrelated application state.