Topic

Mutate data safely

Definition

A mutation is a state-changing request whose UI must represent pending, success, and failure states before synchronized data is refreshed.

In simpler words

Send the write, prevent duplicate clicks while waiting, show failures, and refresh the data that changed.

Interactive product writes use Nest endpoints and TanStack Query mutations in this monorepo.

Open official example (opens in new tab)

After this you can

Model pending, success, and error states
Invalidate affected queries after a write
Distinguish Next-owned actions from Nest-owned product writes

Make the mutation visible

A mutation has a lifecycle, not merely an await expression. Disable or otherwise protect the submit action while pending, retain the draft on failure, and give the user an actionable error message.

After success, invalidate the exact Query resource whose representation is stale. A draft form is local client state; RTK is reserved here for client drafts, not as a duplicate cache of Nest ticket lists.

Create and refresh tickets

const createTicket = useMutation({
  mutationFn: ticketsApi.create,
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['tickets'] }),
});

<button disabled={createTicket.isPending}>Create ticket</button>

The mutation owns its pending state and marks the list stale after success.

Mistake: navigating before the write succeeds

// Wrong — leaves the page even if Nest rejects the body
onClick={() => { createTicket.mutate(draft); router.push('/tickets'); }}

// Right — navigate in onSuccess after accepted write
onSuccess: (ticket) => router.push(`/tickets/${ticket.id}`)

A route change is not a successful mutation.

Use Server Actions by ownership

Definition

Server Actions can suit Next-owned form workflows, but they are not a reason to move the product API into Next.

In simpler words

Choose the mutation path that owns validation, authorization, and persistence.

Keep optimistic updates only when the rollback behavior is clear and the UI benefits are measurable.

Do not use a browser-side success message as proof that a write was authorized.

Live playground

Mutating data playground

Trigger a mutation and identify the pending, error, and success UI.

Idle

Keep in mind

Disable submit controls while the mutation is pending.
Invalidate the precise affected Query key after success.
Keep drafts local or in RTK; keep remote ticket records in Query.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. Server Actions idea?

Concept

Client functions that batch state updates before submitRoute Handlers auto-generated for each form fieldReducers that run on the server via useReducerServer functions you can call from forms/components to mutate

2. Forms with actions?

Syntax

form onSubmit={serverAction} with preventDefault always requiredform method="POST" action="/serverAction" as a URL stringform action={serverAction} only works after "use client"form action={serverAction} progressive enhancement patterns

3. Revalidate after mutation?

Practical

revalidatePath/revalidateTag (or equivalent) so UI data refreshesrouter.refresh() is the only way to update server dataCall fetch again with cache: "reload" to refresh the listrevalidateCache() clears every cache entry after a write

4. When still call Nest from the client?

Logic

Only through a Server Action that proxies to NestFor the course’s Nest tickets API with cookies — mutations via API clientNever — Server Actions fully replace the Nest APIOnly for GET requests; writes must use Server Actions

5. Optimistic UI?

Concept

Wait for the server, then update the UI to stay consistentUpdate UI before server confirms; reconcile on errorUpdate the server first, then optimistically read it backShow a spinner until the mutation resolves, then update

6. Validation location?

Practical

Client validation is enough since Server Actions are trustedValidate only in the database with column constraintsValidate on server even if client validates tooValidate in the browser and skip it in the Server Action

7. Idempotent deletes?

Syntax

Safe to retry; design APIs accordinglyEach retry must create a new tombstone recordA second delete should return a 500 to signal the row is goneDeletes must be wrapped in a transaction to be idempotent

8. Cookies on mutations to Nest?

Logic

Copy the cookie into an Authorization header manuallyInclude credentials on the client requestSet credentials: "omit" so the cookie isn’t duplicatedCookies are sent automatically on cross-origin requests

9. Why not mutate DB from a Client Component directly?

Concept

Client Components can’t run the async functions for the writeThe mutation would run on both the server and the clientThe write would be cached and never reach the databaseExposes credentials/logic; use server boundaries or Nest

10. Which mutation practice is sound?

Practical

Mutate directly during the component’s render passFire the mutation in useEffect on every renderWrite to the Next data cache and skip the databaseServer Action or Nest API + revalidation/invalidate as needed

11. What is this?

Conceptintermediate

'use server';
export async function createTicket(formData) { /* ... */ }

A Route Handler that responds to POST /createTicketA client form handler that runs before submitA Server Action that can be called to mutate data on the serverA middleware function that intercepts the request

12. What is missing after this mutation?

Syntaxadvanced

export async function createPost(data) {
  await db.post.create(data);
  // list still shows stale data
}

A router.push to reload the page after the writerevalidatePath or revalidateTag to refresh cached dataA cache: "no-store" option on the create callA useState update to sync the client list

13. Why include credentials when mutating the Nest API?

Practicalintermediate

await api.post('/tickets', body, { withCredentials: true });

So the browser attaches a CSRF token automaticallySo the request bypasses the CORS preflight checkSo the auth cookie is sent and the guarded endpoint accepts the requestSo the JWT is read from localStorage and added as a header

14. Why is client-only validation insufficient?

Logicadvanced

// only validate in the browser before submit

Client validation runs too late, after the request is sentClients can be bypassed; the server must validate tooBrowser validation only checks types, never valuesServer Actions strip validation attributes from the form

15. What is wrong with this delete?

Conceptadvanced

'use client';
async function remove(id) {
  await db.tickets.delete(id); // in the browser
}

Direct DB mutation from a Client Component exposes credentials and logicThe await is missing, so the delete never completesThe DB call runs on the server, leaking its response to the clientClient Components can’t import async database drivers at all

Checking your session…