Validação do formulário React com React Hook Form e Zod

Criando a ação do servidor com revalidação

Defina a ação

A Ação do Servidor importa o mesmo contactSchema e corre safeParse contra os dados recebidos. Se a análise falhar, os erros do campo nivelado retornarão ao cliente. Se tiver sucesso, a lógica de negócios é executada dentro de um try/catch bloco para garantir que erros inesperados retornem como respostas estruturadas, em vez de travar a ação. Em uma aplicação real, o branch de sucesso executaria uma operação concreta como inserir uma linha em um contacts tabela via Prisma ou enviando um email transacional.

"use server";

import { z } from "zod";
import { contactSchema } from "@/lib/schemas/contact";

type ActionResult =
  | { success: true; fieldErrors?: never }
  | { success: false; fieldErrors: Record<string, string()> };

export async function submitContactForm(
  rawData: unknown
): Promise<ActionResult> {
  const result = contactSchema.safeParse(rawData);

  if (!result.success) {
    const raw = z.flattenError(result.error).fieldErrors;
    
    const fieldErrors: Record<string, string()> = Object.fromEntries(
      Object.entries(raw).filter(
        (entry): entry is (string, string()) =>
          Array.isArray(entry(1)) && entry(1).length > 0
      )
    );
    return { success: false, fieldErrors };
  }

  try {
    
    
    return { success: true };
  } catch (err) {
    console.error("submitContactForm: business logic error", err);
    return {
      success: false,
      fieldErrors: {
        root: ("An unexpected error occurred. Please try again later."),
      },
    };
  }
}

O parâmetro é digitado unknown deliberadamente. Digitando ContactFormData permitiria que o TypeScript aceitasse os dados sem nova análise, anulando a revalidação do lado do servidor.

O z.flattenError() ajudante vira um ZodError em um apartamento { formErrors: string(), fieldErrors: { name: string(), email: string() } } forma, que mapeia diretamente para o setError loop no cliente. (Zod 3 e 4 também têm um error.flatten() método, obsoleto no Zod 4.) Zod digita cada valor de campo como opcional por meio de um registro parcial, de modo que a etapa de filtragem acima restringe undefined entradas e o retorno fieldErrors objeto é um cofre Record.

Por que a revalidação do servidor é importante

A validação do lado do cliente é executada no navegador. Um usuário pode ignorá-lo totalmente desabilitando o JavaScript, manipulando os dados do formulário por meio do DevTools ou enviando solicitações diretamente via cURL ou um bot automatizado. A revalidação do servidor usando o mesmo esquema garante que regras idênticas sejam aplicadas independentemente de como a solicitação chega.

A revalidação do servidor usando o mesmo esquema garante que regras idênticas sejam aplicadas independentemente de como a solicitação chega.

Implemente limitação de taxa e verificação de token CSRF juntamente com validação de esquema. Estas medidas complementares abordam diferentes vetores de ameaças, embora estejam fora do escopo deste tutorial.

Mapeando erros do servidor de volta às entradas com setError

O applyServerErrors ajudante (usado no onSubmit manipulador acima) pega cada chave do servidor fieldErrors objeto e o injeta no estado de erro do React Hook Form. Como o erro se estende na leitura JSX de formState.errors.fieldNameo correto re-renderiza automaticamente e aria-invalid alterna para true na entrada correspondente. O contrato de erro acessível permanece intacto sem adicionar consultas DOM manuais ou ouvintes de eventos.

Para erros inesperados que não são mapeados para um campo específico, o React Hook Form suporta erros no nível raiz via setError('root.serverError', { message: '...' }) (requer react-hook-form >=7.34.0; como alternativa, use setError('root', ...) em versões anteriores). Isso é útil para lidar com casos como falhas de rede ou erros internos do servidor em que nenhum campo individual é o culpado.

Para manter esse padrão DRY em vários formulários, a lógica de mapeamento reside em um auxiliar reutilizável. O auxiliar aceita uma lista explícita de caminhos de campo válidos e roteia quaisquer chaves não reconhecidas para um erro de nível raiz, evitando que chaves fornecidas pelo servidor corrompam silenciosamente o estado do formulário:

import { UseFormSetError, FieldValues, Path } from "react-hook-form";

const SERVER_ERROR_TYPE = "server" as const;

export function applyServerErrors<T extends FieldValues>(
  setError: UseFormSetError<T>,
  fieldErrors: Record<string, string()>,
  validFields: ReadonlyArray<Path<T>>
): void {
  const validSet = new Set<string>(validFields);
  for (const (field, messages) of Object.entries(fieldErrors)) {
    if (!messages || messages.length === 0) continue;
    if (validSet.has(field)) {
      setError(field as Path<T>, {
        type: SERVER_ERROR_TYPE,
        message: messages(0),
      });
    } else {
      
      setError("root" as Path<T>, {
        type: SERVER_ERROR_TYPE,
        message: messages(0),
      });
    }
  }
}

Este auxiliar é genérico em relação ao tipo de valores de campo do formulário, portanto funciona com qualquer esquema Zod e qualquer formulário que use React Hook Form. O validFields parâmetro garante que apenas caminhos de campos de formulário conhecidos sejam passados ​​para setErrorenquanto quaisquer chaves inesperadas da resposta do servidor são roteadas com segurança para um erro no nível raiz. O ContactForm O componente o importa diretamente, substituindo o loop embutido mostrado em rascunhos anteriores.

Testando o esquema com Vitest

Configuração do Vitest

Criar vitest.config.ts na raiz do projeto. Isto configura o @/ alias do caminho para que o Vitest possa resolver as mesmas importações usadas no código da aplicação:

import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./"),
    },
  },
  test: {
    environment: "node",
  },
});

Testes unitários para dados válidos e inválidos

Como o esquema é um módulo independente sem dependências de UI, ele pode ser testado isoladamente com testes de unidade rápidos. Cada teste chama safeParse e afirmações sobre o resultado estruturado.

import { z } from "zod";
import { describe, it, expect } from "vitest";
import { contactSchema } from "@/lib/schemas/contact";

describe("contactSchema", () => {
  it("accepts a valid payload", () => {
    const result = contactSchema.safeParse({
      name: "Jane Doe",
      email: "jane@example.com",
      message: "Hello, this is a valid message.",
    });
    expect(result.success).toBe(true);
  });

  it("rejects a name shorter than 2 characters", () => {
    const result = contactSchema.safeParse({
      name: "J",
      email: "jane@example.com",
      message: "Hello, this is a valid message.",
    });
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(z.flattenError(result.error).fieldErrors.name).toContain(
        "Name must be at least 2 characters."
      );
    }
  });

  it("rejects an invalid email address", () => {
    const result = contactSchema.safeParse({
      name: "Jane Doe",
      email: "not-an-email",
      message: "Hello, this is a valid message.",
    });
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(z.flattenError(result.error).fieldErrors.email).toContain(
        "Please enter a valid email address."
      );
    }
  });

  it("rejects a message shorter than 10 characters", () => {
    const result = contactSchema.safeParse({
      name: "Jane Doe",
      email: "jane@example.com",
      message: "Short",
    });
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(z.flattenError(result.error).fieldErrors.message).toContain(
        "Message must be at least 10 characters."
      );
    }
  });

  it("rejects a message exceeding 500 characters", () => {
    const result = contactSchema.safeParse({
      name: "Jane Doe",
      email: "jane@example.com",
      message: "A".repeat(501),
    });
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(z.flattenError(result.error).fieldErrors.message).toContain(
        "Message must not exceed 500 characters."
      );
    }
  });

  it("rejects a completely empty payload", () => {
    const result = contactSchema.safeParse({});
    expect(result.success).toBe(false);
  });
});

Esses testes afirmam mensagens de erro exatas, que capturam regressões na cópia voltada para o usuário, bem como na lógica de validação.

Executando a suíte

Execute o pacote completo com npx vitest run. Para feedback contínuo durante o desenvolvimento, npx vitest inicia o modo de observação. Adicionar qualquer um dos comandos a um pipeline de CI garante que as alterações de esquema sejam verificadas em cada push.

Lista de verificação de práticas recomendadas de validação de formulário React

1. Esquema único, dois tempos de execução. Defina a validação uma vez no Zod, execute-a no cliente e no servidor.
2. Usar zodResolver para feedback instantâneo do cliente. Ele conecta o React Hook Form ao esquema sem funções de validação manual.
3. Revalidar com safeParse em cada ação do servidor. A validação do lado do cliente sempre pode ser ignorada.
4. Mapeie os erros do servidor de volta aos campos com setError. Isso mantém o ciclo de feedback fechado entre o servidor e a UI.
5. Aplicar aria-invalid e aria-describedby em cada entrada. Os leitores de tela anunciam erros de contexto seguindo as práticas de autoria ARIA.
6. Definir mode para 'onTouched' para evitar erros prematuros. 'onBlur' valida apenas no desfoque e ignora a revalidação nas alterações subsequentes; 'onTouched' faz as duas coisas e geralmente é preferível.
7. Teste de unidade o esquema, não apenas a IU. Os testes de esquema são executados em milissegundos e detectam regressões de regras antecipadamente.
8. Digite os dados do formulário do esquema com z.infer. Nunca duplique manualmente os tipos que o esquema já define.
9. Se o seu formulário lida com uploads de arquivos, valide o tipo e tamanho MIME no cliente com um refinamento Zod personalizado e inspecione os dados brutos FormData entradas no servidor desde que os arquivos carregados chegam no servidor FormData em vez de em um objeto digitado.
10. Desative o botão enviar durante isSubmitting para evitar envios duplicados durante a latência da rede. Lidar com erros do servidor no nível raiz por meio de setError('root.serverError', ...) para falhas que não pertencem a um campo específico.

Para onde ir a partir daqui

Um único esquema Zod, compartilhado entre React Hook Form’s zodResolver e uma ação do servidor Next.js, elimina o desvio de validação. O setError o mapeamento fecha o ciclo de feedback entre o servidor e o cliente. Os atributos ARIA garantem que os estados de erro sejam perceptíveis pela tecnologia assistiva. Vitest bloqueia a correção do esquema independentemente da IU.

Um único esquema Zod, compartilhado entre React Hook Form’s zodResolver e uma ação do servidor Next.js, elimina o desvio de validação.

A partir daqui, adicione validação de upload de arquivo no cliente com z.instanceof(File). Observe que a validação de arquivos do lado do servidor requer inspeção FormData entradas diretamente, já que os arquivos carregados chegam no servidor FormData em vez de em um objeto digitado. Você também pode integrar useFormStatus do React DOM para indicadores de envio de streaming; este gancho deve residir em um componente filho do element, not in the component that renders the form itself. For multi-step forms, split a larger schema across wizard steps using z.pick() ou z.omit() portanto, cada etapa valida apenas seu próprio subconjunto.