tanstack-query

TanStack Query

Constraints

• Structure: Use Query Key Factory (src/features/[feature]/api/query-keys.ts).
• Hooks: Create custom hooks for every query/mutation.
• Keys: Use as const. Establish hierarchical structure (all -> lists -> details).
• Signal: Pass AbortSignal to the API function.
• Invalidation: Invalidate relevant keys in mutation onSuccess.
• Pagination: Include page and filters in the query key.

Bans

• useQuery inside components (Custom hooks are mandatory).
• Manual string query keys.
• Using API responses without validation.
• Ignoring Loading/Error states.

Mandatory Patterns

1. Query Options Factory (v5)

NEVER use inline objects in useQuery or loaders. ALWAYS define queries externally using the queryOptions function.

export const userQueryOptions = (id: string) => queryOptions({ queryKey: userKeys.detail(id), queryFn: ({ signal }) => fetchUser(id, signal) });

// Inside Component or Loader const { data } = useQuery(userQueryOptions(id));

2. Optimistic Updates

ALWAYS use the standard optimistic update pattern for mutations to ensure a snappy UI.

return useMutation({ mutationFn: (taskId: string) => api.patch(/tasks/${taskId}), onMutate: async (taskId) => { await queryClient.cancelQueries({ queryKey: taskKeys.all }); const previousTasks = queryClient.getQueryData<Task[]>(taskKeys.all);

  queryClient.setQueryData<Task[]>(taskKeys.all, (old) => 
    old?.map((t) => t.id === taskId ? { ...t, done: !t.done } : t)
  );
  
  return { previousTasks };
},
onError: (err, taskId, context) => {
  if (context?.previousTasks) {
    queryClient.setQueryData(taskKeys.all, context.previousTasks);
  }
},
onSettled: () => {
  queryClient.invalidateQueries({ queryKey: taskKeys.all });
}

}); };