RTK Query Optimistic Updates

RTK Query Optimistic Updates

Apply optimistic and pessimistic cache updates with onQueryStarted for instant UI feedback with automatic rollback

When to Use

• Toggling a like/favorite and wanting instant UI response
• Reordering items in a list via drag-and-drop
• Editing inline fields where waiting for the server feels sluggish
• Any mutation where the expected server response is predictable

Instructions

1. Use onQueryStarted in the mutation endpoint to perform cache updates before or after the server responds.
2. For optimistic updates: call dispatch(api.util.updateQueryData(...)) immediately inside onQueryStarted, before awaiting the result. Save the return value — it contains an undo function.
3. Wrap the await queryFulfilled in try/catch. On failure, call patchResult.undo() to revert the optimistic change.
4. For pessimistic updates: await queryFulfilled first, then update the cache with the server's response.
5. Always match the exact cache key arguments when calling updateQueryData — a mismatch silently does nothing.
6. Prefer optimistic updates for idempotent operations (toggles, edits). Prefer pessimistic updates when the server assigns critical data (IDs, computed fields).

// Optimistic update — toggle a todo's completed status
toggleTodo: builder.mutation<Todo, { id: string; completed: boolean }>({
  query: ({ id, completed }) => ({
    url: `/todos/${id}`,
    method: 'PATCH',
    body: { completed },
  }),
  async onQueryStarted({ id, completed }, { dispatch, queryFulfilled }) {
    // Optimistically update the cache immediately
    const patchResult = dispatch(
      api.util.updateQueryData('getTodos', undefined, (draft) => {
        const todo = draft.find((t) => t.id === id);
        if (todo) todo.completed = completed;
      })
    );
    try {
      await queryFulfilled;
    } catch {
      // Revert on failure
      patchResult.undo();
    }
  },
}),

// Pessimistic update — server assigns the ID
createTodo: builder.mutation<Todo, { title: string }>({
  query: (body) => ({ url: '/todos', method: 'POST', body }),
  async onQueryStarted(_, { dispatch, queryFulfilled }) {
    try {
      const { data: newTodo } = await queryFulfilled;
      // Update cache with server response
      dispatch(
        api.util.updateQueryData('getTodos', undefined, (draft) => {
          draft.push(newTodo);
        })
      );
    } catch {
      // No cache to revert — the mutation failed before we touched it
    }
  },
}),

Details

updateQueryData arguments: updateQueryData(endpointName, queryArg, updateFn). The queryArg must exactly match what was passed to the query hook. If the query was called with useGetTodosQuery(undefined), pass undefined. If called with useGetTodosQuery({ filter: 'active' }), pass { filter: 'active' }.

Combining with invalidation: You can use optimistic updates AND invalidatesTags together. The optimistic update gives instant feedback, and the invalidation ensures the cache is eventually consistent with the server.

Multiple cache entries: If the same data appears in multiple queries (a list query and a detail query), update both:

async onQueryStarted({ id, title }, { dispatch, queryFulfilled }) {
  const patchList = dispatch(api.util.updateQueryData('getPosts', undefined, (draft) => {
    const post = draft.find((p) => p.id === id);
    if (post) post.title = title;
  }));
  const patchDetail = dispatch(api.util.updateQueryData('getPost', id, (draft) => {
    draft.title = title;
  }));
  try {
    await queryFulfilled;
  } catch {
    patchList.undo();
    patchDetail.undo();
  }
},

Anti-patterns:

• Forgetting to undo() on failure — leaves the UI in a stale state
• Mismatched query args — the update silently does nothing
• Optimistic updates for operations with unpredictable server behavior (payments, inventory)

Source

https://redux-toolkit.js.org/rtk-query/usage/manual-cache-updates

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.