Server State vs Client State: TanStack Query Architecture

1import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
2
3interface Todo {
4  id: string;
5  title: string;
6  completed: boolean;
7}
8
9export function useTodos() {
10  const queryClient = useQueryClient();
11
12  // 1. Query: Stale-while-revalidate caching
13  const todosQuery = useQuery<Todo[]>({
14    queryKey: ['todos'],
15    queryFn: async () => (await fetch('/api/todos')).json(),
16    staleTime: 1000 * 60 * 5, // Fresh for 5 minutes (no background refetch during this time)
17    gcTime: 1000 * 60 * 30,    // Kept in memory for 30 minutes after all subscribers unmount
18  });
19
20  // 2. Optimistic Mutation: Immediate UI feedback + rollback on error
21  const addMutation = useMutation({
22    mutationFn: async (newTodo: { title: string }) => {
23      const res = await fetch('/api/todos', {
24        method: 'POST',
25        headers: { 'Content-Type': 'application/json' },
26        body: JSON.stringify(newTodo),
27      });
28      if (!res.ok) throw new Error('Failed to create todo');
29      return res.json();
30    },
31    // Before network request fires:
32    onMutate: async (newTodo) => {
33      await queryClient.cancelQueries({ queryKey: ['todos'] });
34      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
35
36      // Optimistically update cache with temporary ID
37      queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
38        ...old,
39        { id: 'temp-' + Date.now(), title: newTodo.title, completed: false },
40      ]);
41
42      return { previousTodos }; // Context passed to onError
43    },
44    // If request fails: rollback to saved snapshot
45    onError: (err, newTodo, context) => {
46      if (context?.previousTodos) {
47        queryClient.setQueryData(['todos'], context.previousTodos);
48      }
49    },
50    // Always refetch in background after completion to sync server truth
51    onSettled: () => {
52      queryClient.invalidateQueries({ queryKey: ['todos'] });
53    },
54  });
55
56  return { ...todosQuery, addTodo: addMutation.mutate };
57}