Un solo schema, cero inconsistencias: formulario de registro con Zod 4 + React Hook Form

Step 1 — Definir el schema de Zod con validación cruzada

Aprender a declarar reglas de validación reutilizables y usar superRefine para validar campos dependientes entre sí (password vs confirmPassword).

src/lib/schemas/signup-schema.ts

import { z } from "zod";

export const signupSchema = z
  .object({
    name: z.string().min(2, "El nombre debe tener al menos 2 caracteres"),
    email: z.string().email("Ingresa un correo válido"),
    password: z
      .string()
      .min(8, "La contraseña debe tener al menos 8 caracteres")
      .regex(/[A-Z]/, "Debe contener al menos una mayúscula")
      .regex(/[0-9]/, "Debe contener al menos un número"),
    confirmPassword: z.string(),
  })
  .superRefine((data, ctx) => {
    if (data.password !== data.confirmPassword) {
      ctx.addIssue({
        code: z.ZodIssueCode.custom,
        message: "Las contraseñas no coinciden",
        path: ["confirmPassword"],
      });
    }
  });

export type SignupFormValues = z.infer<typeof signupSchema>;

Step 2 — Construir el formulario con react-hook-form + zodResolver

Conectar el schema de Zod al formulario y ver la validación en tiempo real sin escribir lógica manual de errores.

src/app/signup/page.tsx

"use client";

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { signupSchema, SignupFormValues } from "@/lib/schemas/signup-schema";

export default function SignupPage() {
  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
  } = useForm<SignupFormValues>({
    resolver: zodResolver(signupSchema),
    mode: "onBlur",
  });

  const onSubmit = (data: SignupFormValues) => {
    console.log("Datos válidos:", data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="max-w-sm mx-auto space-y-4 p-6">
      <div>
        <label className="block text-sm font-medium">Nombre</label>
        <input {...register("name")} className="border rounded w-full p-2" />
        {errors.name && <p className="text-red-500 text-sm">{errors.name.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium">Correo</label>
        <input {...register("email")} className="border rounded w-full p-2" />
        {errors.email && <p className="text-red-500 text-sm">{errors.email.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium">Contraseña</label>
        <input type="password" {...register("password")} className="border rounded w-full p-2" />
        {errors.password && <p className="text-red-500 text-sm">{errors.password.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium">Confirmar contraseña</label>
        <input type="password" {...register("confirmPassword")} className="border rounded w-full p-2" />
        {errors.confirmPassword && <p className="text-red-500 text-sm">{errors.confirmPassword.message}</p>}
      </div>

      <button type="submit" disabled={isSubmitting} className="bg-black text-white rounded px-4 py-2 w-full">
        {isSubmitting ? "Creando cuenta..." : "Crear cuenta"}
      </button>
    </form>
  );
}

command: npm run dev

En http://localhost:3000/signup se ve el formulario. Al escribir una contraseña sin mayúscula y salir del campo (blur), aparece de inmediato 'Debe contener al menos una mayúscula' sin necesidad de enviar el formulario.

Step 3 — Testear el schema de forma aislada con Vitest

Validar las reglas de negocio del schema sin depender de la UI, incluyendo el caso de contraseñas que no coinciden.

src/lib/schemas/signup-schema.test.ts

import { describe, it, expect } from "vitest";
import { signupSchema } from "./signup-schema";

describe("signupSchema", () => {
  it("rechaza cuando las contraseñas no coinciden", () => {
    const result = signupSchema.safeParse({
      name: "Ana",
      email: "ana@demo.com",
      password: "Password1",
      confirmPassword: "Password2",
    });

    expect(result.success).toBe(false);
    if (!result.success) {
      const confirmError = result.error.issues.find((i) => i.path[0] === "confirmPassword");
      expect(confirmError?.message).toBe("Las contraseñas no coinciden");
    }
  });

  it("acepta datos válidos", () => {
    const result = signupSchema.safeParse({
      name: "Ana",
      email: "ana@demo.com",
      password: "Password1",
      confirmPassword: "Password1",
    });

    expect(result.success).toBe(true);
  });
});

command: npx vitest run

Step 4 — Reutilizar el schema en el servidor

Aprender a validar el mismo payload en la API route con safeParse, garantizando que las reglas del cliente y del servidor nunca se desincronicen.

src/app/api/signup/route.ts

import { NextRequest, NextResponse } from "next/server";
import { signupSchema } from "@/lib/schemas/signup-schema";

const existingEmails = ["admin@demo.com"];

export async function POST(req: NextRequest) {
  const body = await req.json();
  const parsed = signupSchema.safeParse(body);

  if (!parsed.success) {
    const fieldErrors: Record<string, string> = {};
    parsed.error.issues.forEach((issue) => {
      fieldErrors[issue.path[0] as string] = issue.message;
    });
    return NextResponse.json({ fieldErrors }, { status: 400 });
  }

  if (existingEmails.includes(parsed.data.email)) {
    return NextResponse.json(
      { fieldErrors: { email: "Este correo ya está registrado" } },
      { status: 409 }
    );
  }

  return NextResponse.json({ message: "Usuario creado" }, { status: 201 });
}

Step 5 — Conectar el formulario a la API y propagar errores del servidor

Manejar la respuesta de la API con setError para que un error de negocio (email duplicado) se vea igual que un error de validación de Zod en el cliente.

src/app/signup/page.tsx

"use client";

import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { signupSchema, SignupFormValues } from "@/lib/schemas/signup-schema";
import { useState } from "react";

export default function SignupPage() {
  const [serverError, setServerError] = useState<string | null>(null);
  const [success, setSuccess] = useState(false);

  const {
    register,
    handleSubmit,
    formState: { errors, isSubmitting },
    setError,
  } = useForm<SignupFormValues>({
    resolver: zodResolver(signupSchema),
    mode: "onBlur",
  });

  const onSubmit = async (data: SignupFormValues) => {
    setServerError(null);

    const res = await fetch("/api/signup", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });

    const result = await res.json();

    if (!res.ok) {
      if (result.fieldErrors) {
        Object.entries(result.fieldErrors).forEach(([field, message]) => {
          setError(field as keyof SignupFormValues, {
            type: "server",
            message: message as string,
          });
        });
      } else {
        setServerError(result.message ?? "Ocurrió un error inesperado");
      }
      return;
    }

    setSuccess(true);
  };

  if (success) {
    return <p className="text-green-600 font-medium text-center mt-10">¡Cuenta creada con éxito!</p>;
  }

  return (
    <form onSubmit={handleSubmit(onSubmit)} className="max-w-sm mx-auto space-y-4 p-6">
      <div>
        <label className="block text-sm font-medium">Nombre</label>
        <input {...register("name")} className="border rounded w-full p-2" />
        {errors.name && <p className="text-red-500 text-sm">{errors.name.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium">Correo</label>
        <input {...register("email")} className="border rounded w-full p-2" />
        {errors.email && <p className="text-red-500 text-sm">{errors.email.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium">Contraseña</label>
        <input type="password" {...register("password")} className="border rounded w-full p-2" />
        {errors.password && <p className="text-red-500 text-sm">{errors.password.message}</p>}
      </div>

      <div>
        <label className="block text-sm font-medium">Confirmar contraseña</label>
        <input type="password" {...register("confirmPassword")} className="border rounded w-full p-2" />
        {errors.confirmPassword && <p className="text-red-500 text-sm">{errors.confirmPassword.message}</p>}
      </div>

      {serverError && <p className="text-red-600 text-sm">{serverError}</p>}

      <button type="submit" disabled={isSubmitting} className="bg-black text-white rounded px-4 py-2 w-full">
        {isSubmitting ? "Creando cuenta..." : "Crear cuenta"}
      </button>
    </form>
  );
}

command: npm run dev

Al enviar el formulario con el correo 'admin@demo.com', el input de correo muestra 'Este correo ya está registrado' (viene del servidor, no de Zod client-side). Al cambiar a un correo nuevo y reenviar, aparece el mensaje '¡Cuenta creada con éxito!'.

¿Qué problema resuelve Un solo schema, cero inconsistencias: formulario de registro con Zod 4 + React Hook Form?

En la mayoría de apps React se duplica la lógica de validación entre el frontend (para UX) y el backend (para seguridad), lo que genera bugs cuando alguien actualiza una regla en un lado y se olvida del otro. Además, validar campos dependientes entre sí (como 'confirmar contraseña') suele hacerse a mano con lógica imperativa propensa a errores. Construimos un formulario de registro con validación en tiempo real (nombre, correo, contraseña con reglas de complejidad y confirmación) usando un único schema de Zod 4 que también se reutiliza para validar en el servidor.

¿Qué necesito saber antes de seguir esta clase?

Necesitas Conocimientos básicos de React y hooks, Haber usado formularios controlados o react-hook-form antes, Node.js 18+ instalado, Conceptos básicos de API routes en Next.js. La clase es de nivel intermedio y dura 5 minutos.

¿Qué stack se usa para Zod 4 para validar formularios en React?

El proyecto usa Next.js 14 (App Router), TypeScript, Zod 4, React Hook Form, @hookform/resolvers, Vitest, Tailwind CSS. Todo el código se escribe en pantalla durante la clase.

¿Por qué falla al dejar useForm con el mode por defecto ('onSubmit'), lo que hace que los errores de Zod solo aparezcan después…?

Dejar useForm con el mode por defecto ('onSubmit'), lo que hace que los errores de Zod solo aparezcan después de enviar el formulario, dando la falsa impresión de que la validación en tiempo real 'no funciona'.

¿Por qué falla al poner el path incorrecto en ctx.addIssue dentro de superRefine (por ejemplo path: ['password'] en vez de…?

Poner el path incorrecto en ctx.addIssue dentro de superRefine (por ejemplo path: ['password'] en vez de ['confirmPassword']), lo que asocia el error al campo equivocado en el formulario.

¿Por qué falla al escribir dos schemas distintos (uno para el form y otro 'a mano' en la API route) en vez de importar el mismo…?

Escribir dos schemas distintos (uno para el form y otro 'a mano' en la API route) en vez de importar el mismo signupSchema, reintroduciendo el problema de inconsistencia que Zod resuelve.

¿Por qué falla al confiar solo en la validación del cliente y omitir el safeParse en el servidor, dejando la API abierta a…?

Confiar solo en la validación del cliente y omitir el safeParse en el servidor, dejando la API abierta a requests directos (Postman, curl) con datos inválidos.

¿Hay algún truco que no esté en la documentación oficial?

Cuando el error viene de un refinamiento cruzado como superRefine, usar error.flatten().fieldErrors puede perder el path exacto en casos anidados; en cambio, iterar sobre error.issues y mapear issue.path[0] a cada campo es más robusto para formularios reales. Además, reutilizar el mismo objeto de errores (fieldErrors: Record<string,string>) tanto en el cliente como en la API te permite tener un contrato de errores único entre frontend y backend, algo que casi ningún tutorial de Zod muestra porque solo cubren validación client-side.