62 lines
2.0 KiB
Markdown
62 lines
2.0 KiB
Markdown
# 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 behaviour.
|
|
|
|
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.
|
|
|
|
```ts
|
|
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.
|
|
|
|
```ts
|
|
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
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Open [http://localhost:3000](http://localhost:3000).
|
|
|
|
## Learn more
|
|
|
|
- [TanStack Query — Optimistic Updates](https://tanstack.com/query/latest/docs/framework/react/guides/optimistic-updates)
|
|
- [Next.js App Router](https://nextjs.org/docs/app)
|