TanStack Query: Data Fetching for React

# npm
npm install @tanstack/react-query

# With DevTools (recommended for development)
npm install @tanstack/react-query @tanstack/react-query-devtools

# yarn / pnpm
yarn add @tanstack/react-query @tanstack/react-query-devtools
pnpm add @tanstack/react-query @tanstack/react-query-devtools

import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
import ReactDOM from 'react-dom/client'
import App from './App'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,  // 5 minutes — data stays fresh before refetch
      retry: 2,                   // retry failed requests twice
      refetchOnWindowFocus: true, // refetch when user returns to tab
    },
  },
})

ReactDOM.createRoot(document.getElementById('root')!).render(
  <QueryClientProvider client={queryClient}>
    <App />
    <ReactQueryDevtools initialIsOpen={false} />
  </QueryClientProvider>
)

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

interface Todo {
  id: number
  title: string
  completed: boolean
  userId: number
}

async function fetchTodos(): Promise<Todo[]> {
  const res = await fetch('https://jsonplaceholder.typicode.com/todos')
  if (!res.ok) throw new Error('Failed to fetch todos')
  return res.json()
}

function TodoList() {
  const {
    data: todos,
    isLoading,
    isError,
    error,
    isFetching,  // true when background refetch is happening
    refetch,
  } = useQuery({
    queryKey: ['todos'],        // unique cache key — array format preferred
    queryFn: fetchTodos,
    staleTime: 1000 * 60 * 2,  // override default: 2 minutes fresh
  })

  if (isLoading) return <p>Loading todos...</p>
  if (isError) return <p>Error: {error.message}</p>

  return (
    <div>
      <header>
        <h2>Todos {isFetching && '(updating...)'}</h2>
        <button onClick={() => refetch()}>Refresh</button>
      </header>
      <ul>
        {todos?.map(todo => (
          <li key={todo.id} style={{ opacity: todo.completed ? 0.5 : 1 }}>
            {todo.title}
          </li>
        ))}
      </ul>
    </div>
  )
}

// Fetch a single user — reruns when userId changes
function useUser(userId: number) {
  return useQuery({
    queryKey: ['users', userId],          // key includes the variable
    queryFn: () => fetchUser(userId),
    enabled: !!userId,                    // skip if userId is falsy
  })
}

// Filtered list — reruns when filter changes
function useTodos(filter: 'all' | 'done' | 'pending') {
  return useQuery({
    queryKey: ['todos', { filter }],
    queryFn: () => fetchTodos(filter),
  })
}

// Dependent query — waits for a previous query to finish
function useUserPosts(userId?: number) {
  return useQuery({
    queryKey: ['posts', { userId }],
    queryFn: () => fetchPostsByUser(userId!),
    enabled: !!userId,                    // won't run until userId is available
  })
}

// Usage: chain two queries
function UserWithPosts({ userId }: { userId: number }) {
  const { data: user } = useUser(userId)
  const { data: posts } = useUserPosts(user?.id)  // enabled only after user loads
  // ...
}

import { useMutation, useQueryClient } from '@tanstack/react-query'

async function createTodo(newTodo: { title: string }): Promise<Todo> {
  const res = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(newTodo),
  })
  if (!res.ok) throw new Error('Failed to create todo')
  return res.json()
}

function AddTodoForm() {
  const queryClient = useQueryClient()
  const [title, setTitle] = useState('')

  const mutation = useMutation({
    mutationFn: createTodo,

    // Called immediately on success — before the response propagates
    onSuccess: (newTodo) => {
      // Invalidate and refetch the todos list
      queryClient.invalidateQueries({ queryKey: ['todos'] })

      // OR: manually update the cache without a network request
      queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
        ...old,
        newTodo,
      ])
    },

    onError: (error) => {
      console.error('Create failed:', error)
    },
  })

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault()
    if (!title.trim()) return
    mutation.mutate({ title })
    setTitle('')
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        value={title}
        onChange={e => setTitle(e.target.value)}
        placeholder="New todo..."
        disabled={mutation.isPending}
      />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Adding...' : 'Add Todo'}
      </button>
      {mutation.isError && (
        <p style={{ color: 'red' }}>Error: {mutation.error.message}</p>
      )}
    </form>
  )
}

const toggleTodo = useMutation({
  mutationFn: ({ id, completed }: { id: number; completed: boolean }) =>
    fetch(`/api/todos/${id}`, {
      method: 'PATCH',
      body: JSON.stringify({ completed }),
    }).then(r => r.json()),

  onMutate: async ({ id, completed }) => {
    // Cancel any outgoing refetches so they don't overwrite optimistic update
    await queryClient.cancelQueries({ queryKey: ['todos'] })

    // Snapshot current value for rollback
    const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])

    // Optimistically update cache
    queryClient.setQueryData<Todo[]>(['todos'], old =>
      old?.map(todo => (todo.id === id ? { ...todo, completed } : todo)) ?? []
    )

    // Return snapshot for onError rollback
    return { previousTodos }
  },

  onError: (_err, _vars, context) => {
    // Roll back to snapshot if mutation fails
    if (context?.previousTodos) {
      queryClient.setQueryData(['todos'], context.previousTodos)
    }
  },

  onSettled: () => {
    // Always refetch to ensure cache is in sync with server
    queryClient.invalidateQueries({ queryKey: ['todos'] })
  },
})

// Per-query retry configuration
const { data, error } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  retry: (failureCount, error) => {
    // Don't retry on 404 or 401
    if (error.status === 404 || error.status === 401) return false
    return failureCount < 3
  },
  retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
})

// Global error handling with QueryCache
const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      if (query.state.data !== undefined) {
        // Only show toast if we had data — background refetch failure
        toast.error(`Background refresh failed: ${error.message}`)
      }
    },
  }),
  mutationCache: new MutationCache({
    onError: (error) => {
      toast.error(`Action failed: ${error.message}`)
    },
  }),
})

// Error boundary for declarative error handling
import { QueryErrorResetBoundary } from '@tanstack/react-query'
import { ErrorBoundary } from 'react-error-boundary'

function App() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ resetErrorBoundary }) => (
            <div>
              <p>Something went wrong!</p>
              <button onClick={resetErrorBoundary}>Try again</button>
            </div>
          )}
        >
          <UserList />
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  )
}

// Define all keys in one place
const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: object) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: number) => [...userKeys.details(), id] as const,
}

// Usage — typo-safe, easy to invalidate
const { data } = useQuery({
  queryKey: userKeys.detail(userId),  // ['users', 'detail', 123]
  queryFn: () => fetchUser(userId),
})

// Invalidate all user queries after a bulk action
queryClient.invalidateQueries({ queryKey: userKeys.all })

// Invalidate only a specific user's detail
queryClient.invalidateQueries({ queryKey: userKeys.detail(42) })