Frontend Optimistic Mutations (the write path)
When to Use
Use this skill when you need a portable, framework-agnostic discipline for the write path of any React or React Native app using a query/cache layer. Codifies the optimistic-update lifecycle (cancel in-flight queries → snapshot every affected cache → patch instantly → roll back verbatim on error → invalidate on...
Portable skill — readable by Claude Code, OpenCode, Codex, Cursor, Windsurf, and others.
This skill describes the discipline of the write path — optimistic updates, rollback,
idempotency, cache coherence — not a UI library or a styling system. It builds directly on the
frontend-data-contracts skill (writes go through the typed client) and the
frontend-architecture skill (mutations live in modules/{feature}/hooks/, keyed by a factory).
The goal: a write feels instant (the UI reflects it before the server confirms), is safe
(a failure restores the exact prior state, and a retry never double-charges), and leaves the cache
coherent (the detail view and every list page agree). All three at once — that's the craft.
0. The five core ideas
- The optimistic lifecycle is fixed. cancel → snapshot → patch → (error: roll back) → (settle: invalidate). Every optimistic mutation follows the same five beats.
- Roll back verbatim. On failure, restore the exact snapshot taken before the patch — not a "best guess" re-derivation. Keep the snapshot in mutation context.
- Idempotency is generated once, not per attempt. The key is created at form init (or first intent), so a network retry replays the original server response instead of performing the action twice.
- Caches move in lock-step. A status change patches the detail cache and every list page that contains the entity, so badges never disagree across surfaces.
- Server state never enters the client store. Optimistic state lives in the query cache, not Zustand/Redux. The cache is the single source of truth for server data (per frontend-architecture §4).
1. When to be optimistic (and when not)
| Situation |
Strategy |
| High-confidence, low-conflict write (toggle status, like, mark-paid, reorder) |
Optimistic — patch immediately, roll back on error. |
| Create that returns a server-generated id/number/total |
Pending state, then setQueryData from the server response. A temporary optimistic row is optional; reconcile on success. |
| Destructive or hard-to-reverse write (delete with cascade, send money) |
Confirm first, then optimistic or pending — never silent-optimistic. |
| Write whose result the user can't see yet (background job) |
Pending + toast, invalidate when done. No optimistic patch. |
Optimism is a UX tool for writes you're confident will succeed. If failure is common or expensive to
undo, prefer a pending state.
2. The optimistic lifecycle (TanStack Query)
The canonical shape. Each beat has a job; skipping one breaks correctness.
// modules/invoice/hooks/useInvoiceMutations.ts
interface MarkPaidContext {
previousInvoice: Invoice | undefined; // detail snapshot
previousLists: Array<[readonly unknown[], InvoiceListResponse]>; // every list page snapshot
}
export function useMarkInvoicePaid() {
const queryClient = useQueryClient();
const notifyError = useApiErrorToast();
return useMutation<Invoice, ApiError, { id: InvoiceId }, MarkPaidContext>({
mutationFn: ({ id }) => apiClient.post<Invoice>(INVOICE_API.markPaid(id)),
// 1 + 2 + 3: cancel in-flight reads, snapshot, patch
onMutate: async ({ id }) => {
await queryClient.cancelQueries({ queryKey: invoiceKeys.all }); // (1) no late refetch clobber
const detailKey = invoiceKeys.detail(id);
const previousInvoice = queryClient.getQueryData<Invoice>(detailKey); // (2) snapshot detail
if (previousInvoice) {
queryClient.setQueryData<Invoice>(detailKey, {
// (3) patch detail
...previousInvoice,
status: InvoiceStatus.Paid,
});
}
const previousLists: MarkPaidContext["previousLists"] = [];
for (const [key, list] of queryClient.getQueriesData<InvoiceListResponse>(
{
queryKey: invoiceKeys.lists(),
},
)) {
if (!list) continue;
previousLists.push([key, li
1---
2name: frontend-optimistic-mutations
3description: A portable, framework-agnostic discipline for the write path of any React or React Native app using a query/cache layer.
4category: Document Processing
5source: antigravity
6tags: [react, api, claude, ai, agent, document, security, cro]
7url: https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/frontend-optimistic-mutations
8metadata:
9 source: https://skillmd.com/skills/sickn33/frontend-optimistic-mutations
10---
11
12
13# Frontend Optimistic Mutations (the write path)
14## When to Use
15
16Use this skill when you need a portable, framework-agnostic discipline for the write path of any React or React Native app using a query/cache layer. Codifies the optimistic-update lifecycle (cancel in-flight queries → snapshot every affected cache → patch instantly → roll back verbatim on error → invalidate on...
17
18
19> Portable skill — readable by Claude Code, OpenCode, Codex, Cursor, Windsurf, and others.
20> This skill describes the **discipline of the write path** — optimistic updates, rollback,
21> idempotency, cache coherence — not a UI library or a styling system. It builds directly on the
22> **frontend-data-contracts** skill (writes go through the typed client) and the
23> **frontend-architecture** skill (mutations live in `modules/{feature}/hooks/`, keyed by a factory).
24
25The goal: a write **feels instant** (the UI reflects it before the server confirms), is **safe**
26(a failure restores the exact prior state, and a retry never double-charges), and leaves the cache
27**coherent** (the detail view and every list page agree). All three at once — that's the craft.
28
29---
30
31## 0. The five core ideas
32
331. **The optimistic lifecycle is fixed.** cancel → snapshot → patch → (error: roll back) → (settle: invalidate). Every optimistic mutation follows the same five beats.
342. **Roll back verbatim.** On failure, restore the exact snapshot taken before the patch — not a "best guess" re-derivation. Keep the snapshot in mutation context.
353. **Idempotency is generated once, not per attempt.** The key is created at form init (or first intent), so a network retry replays the original server response instead of performing the action twice.
364. **Caches move in lock-step.** A status change patches the detail cache **and** every list page that contains the entity, so badges never disagree across surfaces.
375. **Server state never enters the client store.** Optimistic state lives in the query cache, not Zustand/Redux. The cache is the single source of truth for server data (per frontend-architecture §4).
38
39---
40
41## 1. When to be optimistic (and when not)
42
43| Situation | Strategy |
44| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
45| High-confidence, low-conflict write (toggle status, like, mark-paid, reorder) | **Optimistic** — patch immediately, roll back on error. |
46| Create that returns a server-generated id/number/total | **Pending state**, then `setQueryData` from the server response. A temporary optimistic row is optional; reconcile on success. |
47| Destructive or hard-to-reverse write (delete with cascade, send money) | **Confirm first**, then optimistic _or_ pending — never silent-optimistic. |
48| Write whose result the user can't see yet (background job) | **Pending + toast**, invalidate when done. No optimistic patch. |
49
50Optimism is a UX tool for writes you're confident will succeed. If failure is common or expensive to
51undo, prefer a pending state.
52
53---
54
55## 2. The optimistic lifecycle (TanStack Query)
56
57The canonical shape. Each beat has a job; skipping one breaks correctness.
58
59```ts
60// modules/invoice/hooks/useInvoiceMutations.ts
61interface MarkPaidContext {
62 previousInvoice: Invoice | undefined; // detail snapshot
63 previousLists: Array<[readonly unknown[], InvoiceListResponse]>; // every list page snapshot
64}
65
66export function useMarkInvoicePaid() {
67 const queryClient = useQueryClient();
68 const notifyError = useApiErrorToast();
69
70 return useMutation<Invoice, ApiError, { id: InvoiceId }, MarkPaidContext>({
71 mutationFn: ({ id }) => apiClient.post<Invoice>(INVOICE_API.markPaid(id)),
72
73 // 1 + 2 + 3: cancel in-flight reads, snapshot, patch
74 onMutate: async ({ id }) => {
75 await queryClient.cancelQueries({ queryKey: invoiceKeys.all }); // (1) no late refetch clobber
76
77 const detailKey = invoiceKeys.detail(id);
78 const previousInvoice = queryClient.getQueryData<Invoice>(detailKey); // (2) snapshot detail
79 if (previousInvoice) {
80 queryClient.setQueryData<Invoice>(detailKey, {
81 // (3) patch detail
82 ...previousInvoice,
83 status: InvoiceStatus.Paid,
84 });
85 }
86
87 const previousLists: MarkPaidContext["previousLists"] = [];
88 for (const [key, list] of queryClient.getQueriesData<InvoiceListResponse>(
89 {
90 queryKey: invoiceKeys.lists(),
91 },
92 )) {
93 if (!list) continue;
94 previousLists.push([key, li