С формами в Next.js проблема обычно начинается не на уровне кнопки submit. Кнопка как раз почти всегда работает. Настоящая путаница начинается позже, когда форма уже живёт в проекте какое-то время. В одном месте ошибка показывается под полем, в другом только общей строкой сверху. Где-то кнопка блокируется на pending, а где-то можно отправить запрос несколько раз подряд. Клиент считает данные валидными, а сервер отвечает, что правило нарушено. Поле уже зелёное, а сохранение всё равно не прошло. В этот момент становится видно, что форма была собрана как кусок UI, а не как контракт.

Используем как примеры паттерны из проекта Workbench. Полезно смотреть на форму не как на набор input и submit, а как на договор между UI, валидацией и местом записи данных. У такого договора есть простая форма - какие данные считаются допустимыми, где и как они проверяются, в каком виде ошибка возвращается в интерфейс, что происходит на pending, когда форма блокируется, что считается успехом, а что общей ошибкой, не привязанной к конкретному полю.

Как только форма описывается так, код перестаёт расползаться. И здесь Zod в Next.js даёт не просто удобную схему, а способ удерживать client и server в одном наборе правил.

Где форма обычно ломается

Пока форма маленькая, соблазн понятен. Есть input, есть локальный state, на submit идёт запрос. Если строка пустая, покажем ошибку. Если сервер ответил 500, выведем что-нибудь наверху. Такой код можно собрать быстро, но он почти всегда начинает расходиться в трёх местах.

Первое место это сами правила. На клиенте одна проверка, на сервере другая. Например, клиент требует длину title от 3 символов, а сервер ещё запрещает определённые слова или отсекает пробелы. В результате пользователь получает неприятный сценарий - форма выглядит валидной, но запись не проходит.

Второе место это формат ошибки. Иногда форма возвращает строку, иногда объект, иногда массив. UI приходится угадывать, что пришло на этот раз.

Третье место это сами состояния формы. У submit почти всегда больше обязанностей, чем просто отправить данные. Нужны pending, disable, field errors, form error, success state и предсказуемое поведение после ответа.

Как только это не собрано в единый контракт, проект начинает жить набором локальных договорённостей.

Что значит форма как контракт

Полезный разворот - сначала не рисовать поля, а определить, что вообще является допустимым результатом работы формы.

Если говорить приземлённо, контракт формы отвечает на несколько вопросов сразу. Какие данные допустимы. Какие ошибки относятся к конкретным полям. Какая ошибка считается общей. Как выглядит pending. Что возвращается при успехе. Может ли UI получить ответ в другой форме. Должны ли client и server пользоваться одним и тем же правилом.

Когда эти вопросы закрыты заранее, интерфейс перестаёт быть местом, где валидация изобретается по ходу дела. В Workbench этот слой удобно собирать вокруг Zod-схемы и единого результата формы.

Одна схема лучше двух похожих проверок

Одна из частых причин путаницы в формах выглядит невинно. На клиенте пишут простую ручную проверку, потому что так быстрее показать сообщение под полем. На сервере делают вторую проверку, потому что серверу всё равно нельзя доверять клиенту. Формально обе стороны правы. Практически проект получает два источника правил.

Рабочий ход здесь другой. Схема одна, а использовать её можно в двух местах.

Ниже упрощённый пример схемы создания заметки.

// src/features/notes/model/noteSchema.ts
import { z } from "zod";

export const noteSchema = z.object({
  title: z
    .string()
    .trim()
    .min(3, "Введите минимум 3 символа")
    .max(80, "Максимум 80 символов"),
  description: z
    .string()
    .trim()
    .max(500, "Максимум 500 символов")
    .optional()
    .or(z.literal("")),
}).refine(
  data => data.title.toLowerCase() !== "test",
  {
    path: ["title"],
    message: "Слишком техническое название для заметки",
  }
);

export type NoteInput = z.infer<typeof noteSchema>;

Здесь важны не конкретные лимиты, а сама модель. Правило живёт не в компоненте и не в обработчике запроса отдельно, а в одном месте. Это уже уменьшает риск расхождения.

Почему safeParse полезнее исключений

Когда схема готова, следующее полезное решение это не валидировать через исключения. Для форм безопаснее и понятнее использовать safeParse. Тогда валидация возвращает результат, с которым UI и server-логика могут работать одинаково.

// src/features/notes/model/validateNote.ts
import { noteSchema } from "./noteSchema";

export function validateNote(input: unknown) {
  return noteSchema.safeParse(input);
}

Смысл safeParse в том, что форма не падает исключением на невалидных данных. Она возвращает управляемый результат. Это хорошо ложится на саму природу формы. Пользователь ввёл что-то не то, это не авария приложения. Это ожидаемый сценарий.

Когда валидация описана так, следующий шаг становится естественным - преобразовать ошибки в единый формат для UI.

Почему flatten удобен для форм

Если Zod уже вернул ошибку, интерфейсу редко нужен весь её внутренний объект. Форме обычно важно знать две вещи: ошибки по полям и общую проблему. Для этого удобно использовать flatten().

// src/features/notes/model/formatZodError.ts
export function formatZodError(error: import("zod").ZodError) {
  const flat = error.flatten();

  return {
    fieldErrors: flat.fieldErrors,
    formError: flat.formErrors[0] ?? null,
  };
}

Это важный момент. Не каждая ошибка должна жить под конкретным input. Есть сообщения, которые относятся ко всей форме. Например, сервер временно недоступен, запись заблокирована, сущность не найдена, данные устарели. Такие случаи неудобно притягивать к полю title или description. Отсюда и полезное разделение - fieldErrors и formError.

Когда оно есть, интерфейс становится заметно вернее. Пользователь видит, что проблема либо в конкретном поле, либо в операции в целом. Не приходится подсовывать общую проблему под первый попавшийся input.

Один и тот же контракт на client и server

Дальше появляется ключевая часть всей схемы. Ту же самую Zod-схему полезно применять и на client, и на server. Но не ради дублирования, а ради разделения обязанностей.

На client валидация нужна для UX. Чтобы рано подсветить ошибку, отключить submit, показать пользователю, что строка не подходит ещё до запроса.

На server она нужна как последняя обязательная граница. Потому что клиентский код можно обойти, подменить, не дождаться его или просто отправить запрос напрямую.

Пример клиентской проверки для одного поля может выглядеть так.

// src/features/notes/ui/NoteTitleForm.tsx
"use client";

import { useMemo, useState } from "react";
import { noteSchema } from "../model/noteSchema";

export default function NoteTitleForm() {
  const [title, setTitle] = useState("");

  const clientResult = useMemo(() => {
    return noteSchema.pick({ title: true }).safeParse({ title });
  }, [title]);

  const titleError = clientResult.success
    ? null
    : clientResult.error.flatten().fieldErrors.title?.[0] ?? null;

  const canSubmit = clientResult.success;

  return (
    <form>
      <input
        value={title}
        onChange={e => setTitle(e.target.value)}
        aria-invalid={!!titleError}
      />

      {titleError ? <p>{titleError}</p> : null}

      <button type="submit" disabled={!canSubmit}>
        Создать
      </button>
    </form>
  );
}

Здесь валидация работает как derived state. Не нужно заводить отдельный state под каждую ошибку и вручную синхронизировать его с input. Схема уже отвечает на вопрос, валидно ли текущее значение.

На server та же логика выглядит иначе по роли, но не по смыслу.

// src/features/notes/actions/createNote.ts
import { noteSchema } from "../model/noteSchema";

export async function createNoteAction(raw: unknown) {
  const parsed = noteSchema.safeParse(raw);

  if (!parsed.success) {
    const flat = parsed.error.flatten();

    return {
      ok: false,
      fieldErrors: flat.fieldErrors,
      formError: flat.formErrors[0] ?? null,
    };
  }

  try {
    const data = parsed.data;

    // запись в store или базу
    // await createNote(data)

    return {
      ok: true,
      fieldErrors: {},
      formError: null,
    };
  } catch {
    return {
      ok: false,
      fieldErrors: {},
      formError: "Не удалось сохранить заметку",
    };
  }
}

Это и есть полезная симметрия. На client схема помогает интерфейсу вести себя предсказуемо. На server эта же схема не пускает невалидные данные в запись. Правило одно, роли разные.

Почему fieldErrors и formError не стоит смешивать

Одна из мелочей, которая заметно улучшает формы, это жёсткое различение двух уровней ошибки. На учебных примерах этим часто пренебрегают, но в реальном проекте смешение быстро даёт мусорный UX.

fieldErrors отвечают на вопрос, что не так с конкретным значением. Пустой title, короткая строка, неправильный формат email, превышение длины description.

formError отвечает на вопрос, почему операция не завершилась как целое. Например, заметка с таким slug уже существует, запись недоступна, сервер не смог сохранить данные, текущая сущность была удалена.

Если всё это сваливать в одну строку, форма становится менее понятной. Пользователь не видит, где нужно исправить поле, а где повторить попытку или просто подождать.

В Next.js это особенно полезно, потому что форма часто живёт рядом с мутацией. А мутация может не пройти по причинам, которые не имеют отношения к самим input.

Форме нужно больше, чем submit

Полезно отдельно проговорить такую вещь. Форма в рабочем приложении обязана уметь не только отправлять данные. Ей нужны disable на невалидном состоянии, pending во время запроса, возврат fieldErrors в правильные места, formError для общей проблемы, success state после завершения и понятное правило, когда UI очищается, а когда остаётся как есть.

Если эти состояния не входят в контракт с самого начала, они всё равно появятся позже, но уже фрагментами. Где-то через отдельный флаг, где-то через строку, где-то через try/catch прямо в компоненте. Отсюда и растёт ощущение, что формы в проекте живут каждая по своим правилам.

Лучше, когда у формы есть один возвращаемый shape.

// src/features/shared/types/formState.ts
export type FormState = {
  ok: boolean;
  fieldErrors: Record<string, string[] | undefined>;
  formError: string | null;
};

Где здесь место React Hook Form

После разговора про контракт легко впасть в другую крайность и начать тащить React Hook Form в каждую форму подряд. Но сам по себе RHF не решает архитектуру. Он полезен там, где форма действительно сложнее простого controlled input.

Например, когда полей много, есть blur-validation, вложенные структуры, динамические списки, кастомные контролы, reset, dirty state, touched state, оптимизация ререндеров. Тогда RHF даёт ощутимую пользу.

Но для одной-двух форм с понятной схемой и простой отправкой лишний слой не всегда нужен. Если задача решается через обычный input, derived validation и предсказуемый ответ формы, RHF может только утяжелить код.

Полезный критерий здесь не модность библиотеки, а сложность сценария. Если без RHF форма остаётся короткой и ясной, значит он пока не обязателен. Если ручное управление уже начинает расползаться на register-подобную логику, touched и reset, значит библиотека становится оправданной.

Что в итоге меняется в голове

Полезный разворот в работе с формами не в том, чтобы добавить Zod или заменить один способ submit на другой. Он в другом. Форма перестаёт восприниматься как локальный кусок интерфейса и начинает восприниматься как контракт между вводом, правилами и результатом.

Сначала есть схема допустимых данных. Потом единый формат ошибки. Потом одинаковая проверка на client и server. Потом понятное разделение между fieldErrors и formError. Потом предсказуемые состояния формы вместо набора случайных флагов.

Когда это собрано, формы перестают быть местом постоянных импровизаций. Они становятся одной из самых дисциплинированных частей проекта.

И именно поэтому в Next.js связка Zod, safeParse, flatten() и единый shape результата работает не как очередной технический приём, а как способ удерживать форму в архитектурно внятном состоянии.

Итог

Если форма в проекте пока воспринимается как input, кнопка и submit, почти наверняка часть проблем ещё просто не успела проявиться. Обычно они приходят вместе с реальными ошибками сервера, повторной отправкой, разными уровнями валидации и несколькими формами, которые начинают жить по разным правилам.

Рабочий путь здесь выглядит так. Одна схема. Одинаковые правила на client и server. safeParse вместо исключений. flatten() для удобного формата ошибок. Отдельно fieldErrors, отдельно formError. И форма как контракт, а не как набор обработчиков вокруг кнопки.

Для примеров в статье использован живой проект Workbench.
Полная последовательная сборка этих паттернов разобрана в Stepik-курсе Next.js II: TypeScript 2026.