re:re:actable
Урок 065 минут чтения

Полный цикл мутации: 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>
    </>
  );
}

Что здесь происходит:

  1. Пользователь отправляет форму — задача сразу появляется в списке полупрозрачной.
  2. Action проверяет данные и пишет в БД, updateTag помечает кэш списка.
  3. Next.js возвращает свежее дерево страницы: tasks приходят из БД, useOptimistic отбрасывает временную запись и показывает настоящую.
  4. При ошибке валидации временная запись исчезает, а ошибка показывается у поля.

Чем обновлять данные после мутации

ФункцияГдеЧто делает
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

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам