React 19 Server Actions с Zod: меньше шаблонного кода FormData

React 19, Server Actions и useActionState меняют подход к созданию форм. Для многих экранов можно продолжать использовать стандартные HTML-формы и обработчики на сервере, вместо того чтобы для каждого случая подключать крупную библиотеку клиентских форм.

После нескольких миграций на эту технологическую стековую сборку в практически каждой операции по-прежнему появлялись одни и те же две строки:

const data = Object.fromEntries(formData);

const result = schema.safeParse(data);if (!result.success) {
  return {
    errors: result.error.flatten().fieldErrors,
  };
}

Экраны входа, процессы регистрации, страницы контактов и редакторы профилей все использовали один и тот же алгоритм: преобразование FormData в объект, обработка с помощью Zod, формирование сообщений об ошибках полей, а затем продолжение работы. Именно такая повторяемость и решает проблему, с которой борется zod-form-action — небольшой инструмент для сочетания Zod с React 19 Server Actions.

Что изменилось в React 19?

useActionState облегчает отслеживание состояния отправки данных, позволяя избегать ручного управления несколькими элементами состояния клиента.

Вместо того чтобы в каждой форме настраивать в браузере обработчики onSubmit, флаги загрузки и механизмы проверки, форма может напрямую отправлять данные на сервер.

Такой подход обычно приводит к следующему:

• Меньше JavaScript отправляется на клиент
• Лучшая производительность при простых операциях
• Проще структура кода обработки действий
• Возможность постепенного улучшения функционала при медленной загрузке или отсутствии клиентского пакета
• Более чёткое разделение задач интерфейса и сервера

Для многих приложений этот подход является оптимальным решением.

Проблема с проверкой форм

На сервер приходит экземпляр объекта FormData.

Прежде чем Zod сможет выполнить проверку, большинство обработчиков преобразуют этот экземпляр в обычный объект.

const data = Object.fromEntries(formData);

const result = schema.safeParse(data);

Сам подход неплохой.

Проблема заключается в том, что каждый обработчик выполняет один и тот же набор действий:

• Преобразование FormData в обычный объект
• Проверка схемы с помощью Zod
• Формирование сообщений об ошибках на уровне полей
• Возврат типизированных значений при успешной обработке
• Переход к коду, отвечающему за логику приложения

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

Представляем zod-form-action

zod-form-action предназначен для уменьшения объема такой повторяющейся работы.

Вместо того чтобы заново реализовывать функции парсинга и проверки в каждом обработчике, он позволяет сосредоточиться на основной логике приложения.

Пакет предполагает наличие следующих компонентов в стеке:

• React 19
• useActionState
• Next.js Server Actions (или другой инструмент для обработки серверных действий)
• Zod
• TypeScript

Цель проста: обеспечить единообразие валидации форм на стороне сервера и упростить её повторное использование.

Для демонстрации доступен рабочий сандбокс в виде этого примера CodeSandbox.

Почему бы просто не использовать React Hook Form?

Этот вопрос задают часто, и ответ на него не является отрицательным.

React Hook Form по-прежнему остается отличной библиотекой.

Он по-прежнему является хорошим выбором для:

• динамических форм
• валидации на стороне клиента
• сложных интерактивных процессов
• массивов полей
• многоэтапных мастер-форм

Не каждой форме нужны все эти функции.

Когда проект уже использует встроенную систему работы с формами React 19 с Server Actions, простой инструмент Zod на сервере может оказаться более подходящим решением, чем полноценный движок форм на стороне клиента.

Эти два инструмента решают разные задачи, а не конкурируют друг с другом напрямую.

Преимущества использования zod-form-action

Команды часто принимают его для:

• Прекратить повторную обработку FormData
• Согласовать поведение проверки данных во всех операциях
• Получать более четкие типы в TypeScript после успешной обработки
• Отображать ошибки полей в стандартизированном формате
• Гармонично интегрироваться с React 19 Server Actions
• Оставить каждую операцию сосредоточенной на правилах своей области

Практические применения

Это решение отлично подходит для повседневных интерфейсов:

• Вход в систему
• Регистрация
• Контакты
• Подписка на рассылку
• Редактирование профиля
• Настройки учетной записи
• Поля дашборда
• Формы CRUD для администратора

Для таких процессов обычно требуются простые, повторяющиеся проверки, а не сложные динамические структуры полей.

Почему выделять этот шаблон

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

Постоянное копирование кода создает уязвимости; вынос общих компонентов в повторно используемый пакет помогает поддерживать проекты в согласованности и позволяет другим улучшать этот инструмент.

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

Важность типобезопасности

Преимущество Zod заключается в проверках во время выполнения в сочетании с надежными типами TypeScript.

Вместо того чтобы постоянно считать каждое значение FormData неизвестным, функция может работать с данными, которые уже были проверены и присвоены определенные типы.

Это обычно означает:

• Лучшая автодополнение в успешных сценариях
• Меньше неожиданностей во время выполнения
• Более чистый код обработчиков
• Упрощенное долгосрочное обслуживание

Производительность

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

Для приложений, уже использующих Server Actions, это соответствует предпочтению React 19 переносить обработку на сервер там, где это полезно.

Что дальше?

Работа над zod-form-action сосредоточена на улучшении пользовательского опыта разработчика.

Среди областей, находящихся в стадии исследования, — это:

• Улучшенная инференция в TypeScript
• Дополнительные инструменты проверки
• Больше примеров
• Шире интеграции с фреймворками
• Более четкая документация

Мнения пользователей пакета будут влиять на ход его разработки.

Часто задаваемые вопросы

Могу ли я использовать React Hook Form с React 19?

Да. React Hook Form по-прежнему остается надежным вариантом, особенно когда формам требуется высокий уровень интерактивности на стороне клиента.

Заменяет ли React 19 React Hook Form?

Нет. React 19 добавляет новые API и паттерны; он не устраняет существующие библиотеки форм. Выбор зависит от сложности формы и места, где должна происходить валидация.

Почему использовать Zod для валидации?

Zod выполняет валидацию во время выполнения и поддерживает согласованность типов TypeScript с результатами валидации, так что неверные данные отклоняются сразу, а корректные остаются с правильными типами.

Предназначен ли zod-form-action только для Next.js?

Нет. Любой приложение React 19, использующее Server Actions и Zod, может извлечь пользу от него в зависимости от структуры архитектуры.

Заключение

React 19 побуждает команды к более простому созданию форм.

Нативные HTML-формы, useActionState, Server Actions и Zod вместе позволяют обеспечить надежную и типизированную валидацию без необходимости постоянного использования крупных инструментов для работы с формами на стороне клиента.

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

zod-form-action был создан именно с учётом этой цели.

Установите его с страницы пакета в npm.