Полный цикл мутации: useActionState, useOptimistic и обновление данных
На этой странице
Мутация в App Router проходит цепочку: форма (<form action={...}> — работает и до загрузки JS) → Server Action (проверки и запись в БД) → обновление данных на экране (updateTag/revalidateTag/revalidatePath для кэша, refresh() для некэшированных данных, redirect() для перехода) → ответ интерфейсу. На клиенте useActionState хранит результат последней отправки (ошибки полей, сообщение) и флаг pending, useFormStatus даёт статус формы вложенным компонентам (кнопке), useOptimistic показывает ожидаемый результат сразу и откатывается сам, если Action упала. После успешной Action Next.js в том же ответе присылает обновлённый RSC-пейлоад текущей страницы — отдельный запрос не нужен.
Вопрос
Как связать форму, Server Action, состояние ошибок, оптимистичное обновление и обновление кэша в одну корректную цепочку?
Схема
<form action={formAction}>
│ submit (POST, FormData)
▼
Server Action
├─ requireUser, Zod, права
├─ db.update(...)
├─ updateTag('tasks') ← пометить кэш устаревшим (пользователь сразу видит своё)
└─ return { errors } | redirect('/tasks')
▼
Ответ: результат Action + обновлённое дерево страницы
▼
useActionState → state; useOptimistic → заменяется реальными даннымиServer Action
// app/tasks/actions.ts
'use server';
import { z } from 'zod';
import { updateTag } from 'next/cache';
import { requireUser } from '@/lib/dal';
const TaskSchema = z.object({
title: z.string().trim().min(3, 'Минимум 3 символа').max(120),
});
export type FormState = { errors?: { title?: string[] }; message?: string; values?: { title: string } };
export async function createTask(_prev: FormState, formData: FormData): Promise<FormState> {
const user = await requireUser();
const raw = { title: String(formData.get('title') ?? '') };
const parsed = TaskSchema.safeParse(raw);
if (!parsed.success) {
// Возвращаем введённое значение, чтобы не потерять его после сброса формы
return { errors: parsed.error.flatten().fieldErrors, values: raw };
}
await db.task.create({ data: { title: parsed.data.title, ownerId: user.id } });
updateTag(`tasks-${user.id}`);
return { message: 'Задача добавлена' };
}Данные страницы с тегом
// app/tasks/page.tsx
import { cacheTag } from 'next/cache';
import { requireUser } from '@/lib/dal';
import { TaskBoard } from './task-board';
async function getTasks(userId: string) {
'use cache';
cacheTag(`tasks-${userId}`);
return db.task.findMany({ where: { ownerId: userId }, orderBy: { createdAt: 'desc' } });
}
export default async function Page() {
const user = await requireUser(); // читает cookies() — данные запроса
const tasks = await getTasks(user.id);
return <TaskBoard tasks={tasks} />;
}При включённых Cache Components чтение cookies() должно происходить внутри границы Suspense — для этого рядом кладут loading.tsx или выносят requireUser и список в дочерний компонент, обёрнутый в <Suspense>.
Форма с ошибками, pending и оптимистичным списком
// app/tasks/task-board.tsx
'use client';
import { useActionState, useOptimistic } from 'react';
import { useFormStatus } from 'react-dom';
import { createTask, type FormState } from './actions';
function SubmitButton() {
const { pending } = useFormStatus();
return <button disabled={pending}>{pending ? 'Добавляем…' : 'Добавить'}</button>;
}
export function TaskBoard({ tasks }: { tasks: Task[] }) {
const [optimisticTasks, addOptimistic] = useOptimistic(
tasks,
(state, title: string) => [{ id: `temp-${Date.now()}`, title, pending: true }, ...state],
);
const [state, formAction] = useActionState(async (prev: FormState, formData: FormData) => {
const title = String(formData.get('title') ?? '').trim();
if (title.length >= 3) addOptimistic(title); // показать сразу
return createTask(prev, formData); // при ошибке оптимистичная задача исчезнет сама
}, {});
return (
<>
<form action={formAction} noValidate>
<label htmlFor="title">Новая задача</label>
<input
id="title"
name="title"
defaultValue={state.values?.title}
aria-invalid={Boolean(state.errors?.title)}
aria-describedby={state.errors?.title ? 'title-error' : undefined}
/>
{state.errors?.title && <p id="title-error">{state.errors.title[0]}</p>}
<SubmitButton />
<p role="status">{state.message}</p>
</form>
<ul>
{optimisticTasks.map((t) => (
<li key={t.id} style={{ opacity: t.pending ? 0.6 : 1 }}>{t.title}</li>
))}
</ul>
</>
);
}Что здесь происходит:
- Пользователь отправляет форму — задача сразу появляется в списке полупрозрачной.
- Action проверяет данные и пишет в БД,
updateTagпомечает кэш списка. - Next.js возвращает свежее дерево страницы:
tasksприходят из БД,useOptimisticотбрасывает временную запись и показывает настоящую. - При ошибке валидации временная запись исчезает, а ошибка показывается у поля.
Чем обновлять данные после мутации
| Функция | Где | Что делает |
|---|---|---|
updateTag(tag) | Только Server Action | Немедленно истекает кэш тега; следующий рендер ждёт свежие данные (read-your-writes) |
revalidateTag(tag, 'max') | Action, Route Handler, вебхук | Фоново: отдаётся старое, пока готовится новое |
revalidatePath('/tasks') | Action, Route Handler | Инвалидирует кэш маршрута целиком |
refresh() | Только Server Action | Перерисовать текущую страницу с некэшированными данными (счётчики, уведомления) |
redirect('/tasks/123') | Action | Переход после создания; вызывать после инвалидации |
router.refresh() | Клиент | Перезапросить текущий маршрут с сервера |
Без формы: вызов Action из обработчика
'use client';
import { useTransition } from 'react';
import { toggleDone } from './actions';
export function DoneCheckbox({ task }: { task: Task }) {
const [isPending, startTransition] = useTransition();
return (
<input
type="checkbox"
checked={task.done}
disabled={isPending}
aria-label={`Выполнено: ${task.title}`}
onChange={() => startTransition(() => toggleDone(task.id))}
/>
);
}Вызов из обработчика оборачивают в startTransition, чтобы получить isPending и не блокировать интерфейс. Такой вариант не работает без JS — для критичных форм предпочтительнее <form action>.
Частые ошибки
- Забыть обновить кэш → после сохранения на экране старые данные.
redirect()внутриtry/catch— он работает через исключение, иcatchего «съест».- Хранить в
useStateкопию серверных данных → послеupdateTagона не обновится. - Валидация только на клиенте.
- Вызывать
setStateпослеawaitвнутри transition безstartTransition— обновление не попадёт в тот же переход.
Мини-шпаргалка
<form action> + useActionState(action, initial) → [state, formAction, pending]
useFormStatus() → pending для кнопки внутри формы
useOptimistic(serverData, reducer) → мгновенный UI с автооткатом
Action: auth → Zod → права → db → updateTag → return | redirect
updateTag — сразу; revalidateTag(tag,'max') — фоново; refresh() — некэшированное
Вызов из onChange → startTransition