* refactor(examples/react/nextjs-app-optimistic-updates): type the form submit handlers with 'React.SubmitEvent' instead of the deprecated 'React.FormEvent' * chore(examples/react/nextjs-app-optimistic-updates/package.json): raise the '@types/react' minimum to '^19.2.10' for 'React.SubmitEvent' |
History
|
|
|---|---|---|
| .. | ||
| app | ||
| components | ||
| services/todos | ||
| .gitignore | ||
| eslint.config.js | ||
| next.config.js | ||
| package.json | ||
| README.md | ||
| tsconfig.json | ||
TanStack Query — Next.js App Router Optimistic Updates
This example demonstrates optimistic updates with TanStack Query v5 in a Next.js 14 App Router project.
What it shows
A todo list where items appear in the UI immediately after submission — before the server confirms. The server randomly fails ~30% of the time so you can observe automatic rollback behavior.
Two approaches are shown side by side via a tab toggle:
Approach 1 — Via UI Variables (simpler)
Render the pending item directly from mutation.variables. No cache touching required. On error, the pending item simply disappears and an error message is shown.
const mutation = useMutation({ mutationFn: addTodo, onSettled: invalidate })
// In JSX:
{mutation.isPending && <li style={{ opacity: 0.5 }}>{mutation.variables}</li>}
Best when: the mutation input maps 1-to-1 to what you'd show while pending.
Approach 2 — Via Cache Manipulation (onMutate + rollback)
onMutate cancels in-flight refetches, snapshots the current cache, and writes an optimistic item directly into the cache. onError restores the snapshot.
const mutation = useMutation({
mutationFn: addTodo,
onMutate: async (text) => {
await queryClient.cancelQueries({ queryKey: ['todos'] })
const previousTodos = queryClient.getQueryData<Todo[]>(['todos'])
queryClient.setQueryData<Todo[]>(['todos'], (old = []) => [
...old,
optimistic,
])
return { previousTodos }
},
onError: (_err, _vars, context) => {
queryClient.setQueryData(['todos'], context?.previousTodos)
},
onSettled: () => queryClient.invalidateQueries({ queryKey: ['todos'] }),
})
Best when: you need fine-grained control or the optimistic shape differs from mutation.variables.
Running the example
npm install
npm run dev
Open http://localhost:3000.