Query keys and options

From: all three projects. The key examples come from the e-commerce platform; the query options come from the resort website and the company website with its CMS.

A key factory in one fileCopy Anchor Link

Query keys are never written inline. They come from one object in src/configs/query-keys.ts:

export const queryKeys = {
  orderHistory: {
    all: ['order-history'] as const,
    list: (page: number) => [...queryKeys.orderHistory.all, 'list', page] as const,
    infinite: () => [...queryKeys.orderHistory.all, 'infinite'] as const,
  },
  product: {
    suggestions: (query: string) => ['product', 'suggestions', query] as const,
  },
} as const;

Shared prefixes make invalidation simpleCopy Anchor Link

TanStack Query invalidates by prefix. Because every order history key starts with ['order-history'], one call refreshes the desktop table and the mobile list together:

queryClient.invalidateQueries({ queryKey: queryKeys.orderHistory.all });

After checkout, that's the only line needed. Nobody has to remember which screens show orders.

Same endpoint, different key, for infinite queriesCopy Anchor Link

The desktop table and the mobile list call the same API, but list(page) and infinite() are different keys. They still share the prefix, so invalidation works for both.

Normalise inputs before they go in the keyCopy Anchor Link

const normalizedQuery = query.trim();
// queryKey: queryKeys.product.suggestions(normalizedQuery)

"nike" and "nike " are the same search. Trimming before building the key gives them one cache entry instead of two.

Filters in the key reset lists for freeCopy Anchor Link

Put filters, search text and sort order into the key:

const blogParams = { search: debouncedSearch.trim() || undefined, dir };
// key: ['blogs', 'list', blogParams, 'infinite']

When a filter changes, the key changes, and TanStack Query starts a fresh list from initialPageParam. No code has to reset a page counter by hand.

Query options instead of custom hooksCopy Anchor Link

Every GET gets a queryOptions() factory in src/lib/query-options/<feature>.query-options.ts. The key, fetcher and staleTime are defined once, and every caller reuses them.

In the resort website's admin dashboard, the blog editor started with a custom hook:

export function useBlogBySlugQuery(slug: string) {
  return useQuery({
    queryKey: QUERY_KEYS.blogs.detail(slug),
    queryFn: () => getBlogBySlug(slug),
    enabled: !!slug,
  });
}

I replaced it with query options next to the blog list's:

export const blogBySlugQueryOptions = (slug: string) =>
  queryOptions({
    queryKey: QUERY_KEYS.blogs.detail(slug),
    queryFn: () => getBlogBySlug(slug),
    enabled: !!slug,
  });

const { data, isLoading } = useQuery(blogBySlugQueryOptions(slug));

A hook only works inside a component. Query options work everywhere a query is needed:

queryOptions() also carries the return type, so useQuery(options).data and queryClient.getQueryData(options.queryKey) are typed without generics.