react-query

TanStack Query (react-query) Best Practices

This document outlines the definitive best practices for using TanStack Query in our React applications. Adhering to these guidelines ensures consistent, performant, and maintainable data fetching and state management.

1. Query Keys: The Foundation of Caching

ALWAYS use stable, descriptive array keys. These are fundamental for caching, refetching, and invalidation. For dynamic data, embed parameters directly into the array.

✅ GOOD: Stable Array Keys & Key Factories

// 1. Simple, static key
const USERS_KEY = ['users'];

// 2. Dynamic key with parameters
const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: { status?: string; page?: number }) =>
    [...userKeys.lists(), { filters }] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
};

// Usage:
// useQuery(userKeys.all, fetchAllUsers);
// useQuery(userKeys.list({ status: 'active', page: 1 }), fetchUsers);
// useQuery(userKeys.detail(userId), fetchUserById);

❌ BAD: Unstable or Generic Keys

// String keys are less flexible for dynamic data and filtering
useQuery('users', fetchUsers);

// Anonymous object keys are unstable and break caching
useQuery(['users', { id: userId }], fetchUserById); // Object literal creates new reference each render

2. Custom Hooks: Encapsulate Logic

ALWAYS wrap useQuery and useMutation calls in custom hooks. This centralizes data fetching logic, improves reusability, enhances type safety, and keeps components clean.

✅ GOOD: Dedicated Custom Hooks

// hooks/useUsers.ts
import { useQuery } from '@tanstack/react-query';
import { fetchUsers, User } from '../api'; // Assume api.ts defines fetchUsers

const userKeys = {
  all: ['users'] as const,
  list: (filters: { status?: string }) => [...userKeys.all, { filters }] as const,
};

export function useUsers(filters?: { status?: string }) {
  return useQuery<User[], Error>({
    queryKey: userKeys.list(filters || {}),
    queryFn: () => fetchUsers(filters),
  });
}

// components/UserList.tsx
import { useUsers } from '../hooks/useUsers';

function UserList({ statusFilter }: { statusFilter?: string }) {
  const { data: users, isLoading, error } = useUsers({ status: statusFilter });

  if (isLoading) return <div>Loading users...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {users?.map((user) => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}