Как валидировать формы схемой Zod
На этой странице
Zod — библиотека схем валидации для TypeScript: вы описываете форму данных один раз (z.object({...})), а Zod проверяет значения во время выполнения и выводит из схемы TypeScript-тип (z.infer). С react-hook-form схема подключается через zodResolver, и правила валидации уходят из JSX в одно место. Ту же схему можно использовать на сервере — в Server Action или API — чтобы клиент и сервер проверяли данные одинаково.
Вопрос
Как валидировать форму схемой Zod? Как подключить ее к react-hook-form, сравнить два поля (подтверждение пароля) и переиспользовать схему на сервере?
Схема
// features/auth/schema.ts
import { z } from "zod";
export const signUpSchema = z
.object({
name: z.string().trim().min(2, "Минимум 2 символа"),
email: z.string().trim().email("Некорректный email"),
age: z.coerce.number().int().min(18, "Регистрация с 18 лет"),
password: z.string().min(8, "Минимум 8 символов").regex(/\d/, "Нужна хотя бы одна цифра"),
confirmPassword: z.string(),
website: z.string().url("Некорректный адрес").optional().or(z.literal("")),
})
.refine((data) => data.password === data.confirmPassword, {
message: "Пароли не совпадают",
path: ["confirmPassword"], // к какому полю привязать ошибку
});
export type SignUpValues = z.infer<typeof signUpSchema>;Подключение к react-hook-form
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { signUpSchema, type SignUpValues } from "./schema";
export function SignUpForm() {
const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<SignUpValues>({
resolver: zodResolver(signUpSchema),
defaultValues: { name: "", email: "", password: "", confirmPassword: "", website: "" },
mode: "onTouched",
});
return (
<form onSubmit={handleSubmit((data) => api.signUp(data))} noValidate>
<input {...register("email")} aria-invalid={!!errors.email} />
{errors.email && <p role="alert">{errors.email.message}</p>}
<input type="password" {...register("password")} />
{errors.password && <p role="alert">{errors.password.message}</p>}
<input type="password" {...register("confirmPassword")} />
{errors.confirmPassword && <p role="alert">{errors.confirmPassword.message}</p>}
<button disabled={isSubmitting}>Создать аккаунт</button>
</form>
);
}В onSubmit приходят уже проверенные и преобразованные данные (trim, числа после coerce).
Та же схема на сервере
// app/actions.ts
"use server";
import { signUpSchema } from "@/features/auth/schema";
export async function signUp(_prev: unknown, formData: FormData) {
const result = signUpSchema.safeParse(Object.fromEntries(formData));
if (!result.success) {
return { errors: result.error.flatten().fieldErrors }; // { email: ["Некорректный email"] }
}
await db.user.create({ data: result.data });
return { errors: null };
}safeParse не бросает исключение, а возвращает { success, data | error }.
Частые приемы
| Задача | Zod |
|---|---|
| необязательное поле | .optional(), пустая строка — .or(z.literal("")) |
число из <input> | z.coerce.number() |
| перечисление | z.enum(["card", "sbp"]) |
| зависимость полей | .refine / .superRefine с path |
| разные схемы по типу | z.discriminatedUnion("type", [...]) |
| трансформация | .transform((v) => v.toLowerCase()) |
| асинхронная проверка | .refine(async (v) => ...) + parseAsync |
Что важно помнить
- Схема — единственный источник правил и типов: не дублируйте правила в
registerи в схеме. - Значения полей формы — строки; для чисел нужны
z.coerce.number()илиvalueAsNumber. - Клиентская схема помогает пользователю, серверная проверка защищает данные — выполняйте обе.
- Сообщения об ошибках пишите для пользователя: что именно исправить.
- Аналоги Zod: Valibot (меньше размер), Yup (часто в старых проектах), ArkType; для всех есть резолверы в
@hookform/resolvers.
Мини-шпаргалка
z.object({...}) → z.infer<typeof schema> для типов. useForm({ resolver: zodResolver(schema) }). Сравнение полей — .refine(fn, { path }). Числа — z.coerce.number(). На сервере — schema.safeParse(Object.fromEntries(formData)).
Документация
Zod: Documentation, React Hook Form: Schema Validation, @hookform/resolvers, Next.js: Form validation.