Ações de formulário: substituindo rotas de API para mutações

Em aplicações tradicionais do Next.js, os envios de formulário exigem um componente do cliente com um manipulador onSubmit que chama uma função de busca para enviar dados via POST a uma rota de API. Esse padrão funciona, mas exige escrever e manter separadamente tanto a lógica de busca no cliente quanto o manipulador da rota no servidor.

Com as Ações do servidor, você substitui a chamada de busca e a rota da API por uma única função. O elemento de formulário recebe a Ação do servidor como sua propriedade action: <form action={serverAction}>. O React intercepta o envio e chama a ação automaticamente com os dados do formulário.

A Ação do servidor recebe automaticamente um objeto FormData como argumento quando é acionada por um formulário. Você acessa campos individuais usando formData.get('email'), que retorna o valor como uma string. Todos os métodos padrão de FormData estão disponíveis, incluindo getAll() para campos de seleção múltipla.

Uma Ação do servidor pode retornar um valor serializável que o cliente pode usar. Retornar um objeto de erro como { error: 'Email already exists' } ou um indicador de sucesso como { success: true } permite que o cliente atualize a interface adequadamente sem recarregar a página inteira.

Como a ação do formulário é uma Ação do servidor, o componente da página que hospeda o formulário não precisa ser um componente do cliente. O servidor renderiza o formulário como HTML estático, e somente as partes interativas, como a exibição de erros, exigem JavaScript no cliente. Isso reduz significativamente o pacote do cliente.

Um formulário com action={serverAction} funciona sem o JavaScript habilitado. O navegador realiza um POST de formulário HTML padrão, o servidor executa a ação e retorna a página atualizada. Esse verdadeiro aprimoramento progressivo permite que o formulário funcione adequadamente em todos os ambientes.

Depois que uma Ação do servidor altera os dados, os dados da página armazenados em cache precisam ser atualizados. Chamar revalidatePath('/dashboard') dentro da ação invalida o cache do Next.js para esse caminho, fazendo com que a próxima solicitação busque dados atualizados. Essa é a maneira padrão de manter atualizadas as páginas renderizadas no servidor após mutações.

revalidateTag('user-data') oferece uma invalidação de cache mais específica do que revalidatePath. Você marca as chamadas de busca com next: { tags: ['user-data'] } e depois invalida de uma só vez todos os dados marcados dentro da Ação do servidor, independentemente dos caminhos que exibem esses dados.

As Ações do servidor podem redirecionar o usuário para uma nova página após uma mutação bem-sucedida, chamando redirect('/success') a partir do módulo next/navigation. Esse redirecionamento é tratado no servidor, o que significa que o navegador recebe uma resposta de navegação adequada em vez de um redirecionamento no cliente.

As Ações do servidor não se limitam a envios de formulário. Para cliques em botões e outros acionamentos que não sejam de formulários, envolva a chamada da ação em startTransition(() => action(arg)). Isso marca a navegação como uma transição, permitindo que o React mantenha a interface atual visível enquanto a ação é executada no servidor.

As Ações do servidor são o local adequado para a validação no servidor. Valide os campos de FormData, retorne erros de validação se eles falharem e só prossiga com a mutação se todos os campos forem válidos. Bibliotecas como Zod se integram bem nesse ponto: analise o FormData em um esquema tipado e retorne o mapa de erros em caso de falha.

O que uma Ação do servidor recebe como argumento quando é acionada pelo envio de um formulário?

As Ações do servidor substituem o padrão de mutação com chamada de busca e rota de API. A propriedade action do formulário aceita diretamente uma Ação do servidor, que recebe um objeto FormData. As ações retornam resultados serializáveis para atualizações da interface do cliente, oferecem revalidatePath e revalidateTag para invalidação do cache e funcionam progressivamente sem JavaScript.