The Complete Production SOP: How to Deploy and Run TanStack Query v5 Optimistic Updates & Cache Mutations in Autonomous AI Agents

---
name: "tanstack-query-v5-optimistic"
description: "Execute resilient server mutations with instant optimistic cache updates and automatic rollback."
metadata:
  author: "TanStack"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "optimistic update tanstack query v5"
  - "cancel queries queryclient"
  - "rollback onmutate react query"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

import { useMutation, useQueryClient } from '@tanstack/react-query';
import type { Todo, NewTodoPayload } from './types';

export const useAddTodoMutation = () => {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (newTodo: NewTodoPayload): 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();
    },
    onMutate: async (newTodo) => {
      // Step 1: Cancel any outgoing refetches to avoid overwriting optimistic update
      await queryClient.cancelQueries({ queryKey: ['todos'] });

      // Step 2: Snapshot the previous value
      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);

      // Step 3: Optimistically update to the new value
      queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
        ...old,
        { id: `temp-${Date.now()}`, ...newTodo, completed: false },
      ]);

      // Step 4: Return context object with snapshotted value
      return { previousTodos };
    },
    onError: (_err, _newTodo, context) => {
      // Rollback to previous state on failure
      if (context?.previousTodos) {
        queryClient.setQueryData(['todos'], context.previousTodos);
      }
    },
    onSettled: () => {
      // Always refetch after error or success to synchronize with server
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });
};

claude 'Refactor src/features/comments/usePostComment.ts to use an optimistic update tanstack query v5 with cancel queries queryclient and rollback onmutate react query.'

import { renderHook, waitFor } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import React from 'react';
import { describe, it, expect, vi } from 'vitest';
import { useAddTodoMutation } from './useAddTodoMutation';

describe('useAddTodoMutation', () => {
  it('rolls back cache on server error', async () => {
    const queryClient = new QueryClient();
    queryClient.setQueryData(['todos'], [{ id: '1', title: 'Existing', completed: false }]);

    vi.spyOn(global, 'fetch').mockRejectedValueOnce(new Error('Server Down'));

    const wrapper = ({ children }: { children: React.ReactNode }) => (
      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
    );

    const { result } = renderHook(() => useAddTodoMutation(), { wrapper });

    result.current.mutate({ title: 'New Task' });

    await waitFor(() => expect(result.current.isError).toBe(true));
    expect(queryClient.getQueryData(['todos'])).toEqual([
      { id: '1', title: 'Existing', completed: false },
    ]);
  });
});