Mutations

Use your ready utility tree and QueryClient from the RPC quick start or HTTP quick start. In these examples, users.create accepts a name and returns a user with id and name. Import MutationObserver from @tanstack/query-core for imperative execution.

Execute a write

Build the options once. Supply each mutation’s variables when it runs:

const createUser = new MutationObserver(
  queryClient,
  rpc.users.create.mutationOptions({
    onSuccess: () => queryClient.invalidateQueries({ queryKey: rpc.users.key() }),
  }),
)
const created = await createUser.mutate({ name: 'Ada' })

HTTP variables contain the complete decoded request:

const createHttpUser = new MutationObserver(
  queryClient,
  http.users.create.mutationOptions({
    onSuccess: () => queryClient.invalidateQueries({ queryKey: http.users.key() }),
  }),
)
const createdHttpUser = await createHttpUser.mutate({ payload: { name: 'Ada' } })

Native mutation hooks accept the same options. Callbacks infer the result, variables, and execution errors. Mutation keys identify the operation and exclude variables. Successful undefined remains undefined.

Choose cache updates

Choose how your callbacks refresh reads after a write. Invalidate affected generated prefixes, seed a known result with setQueryData, or apply an optimistic write. The library derives builders from the contract. The call site chooses read or write semantics. Buffered multipart endpoints support mutations only.

See HTTP uploads, Handle Failures, and Cancellation for their execution boundaries.