TanStack Query

mutationOptions() adapter for @tanstack/react-query, type-safe mutations with error bridging.

Basic mutationOptions

Simple useMutation with mutationOptions(), try email "taken@example.com" for a validation error.

Status:Idle

Result:

Mutation with callbacks

onSuccess shows a toast + invalidates queries, onError uses type guards, retry skips validation errors.

Status:Idle

Result:

Optimistic updates

Todos toggle instantly via onMutate, reverts on server error (30% random failure rate).

Mutation status:Idle

Note: In production, you would pair this with a Route Handler (GET endpoint) so invalidateQueries can refetch fresh data from the server.

Navigation errors

Navigation functions (redirect, notFound, forbidden, unauthorized) work automatically with mutationOptions().

Status:Idle

Result:

Note: The adapter's mutationOptions() automatically composes throwOnErrorto re-throw navigation errors during React's render phase and retry to skip them. No additional configuration is required.