Server Actions
Prioridade: P1 (ALTA)
[!WARNING] Se o projeto usar o diretório
pages/em vez do App Router, ignore este skill completamente.
Lide com envios de formulários e mutações sem criar endpoints de API.
Diretrizes de Implementação
-
Diretiva: Sempre inicie o arquivo ou função com
'use server'. AcesseformData.get('title')para campos de formulário tipados. Exporte funções assíncronas para mutações. -
Manipulação de Formulários: Use a prop
actiondo<form>para disparar ações viaaction={createPost}. UseuseFormStatus()para estadospending—disabled={pending}em botões. UseuseActionState(React 19/Next.js 15) para estado de formulário comaction={action}e<form action={action}>. -
Atualização de Dados: Dispare atualizações de UI usando
revalidatePath('/')ourevalidateTag('tag-name')após uma mutação bem-sucedida. -
Interatividade: Para disparos não vinculados a formulários, invoque ações usando o hook
useTransitionpara lidar com UI de carregamento e evitar bloqueio da página. -
Atualizações Otimistas: Use
useOptimisticpara exibir o estado esperado da UI imediatamente antes de o servidor confirmar a mutação. -
Segurança: Sanitize todas as entradas de
FormData. Realize verificações de autorização dentro de cada ação (await auth()). Limite uploads de arquivos por tamanho e tipo MIME. -
Formulário:
<form action={createPost}>(Melhorias progressivas funcionam sem JS). -
Manipulador de Eventos:
onClick={() => createPost(data)}. -
Estado Pendente: Use o hook
useFormStatus(deve estar dentro de um componente renderizado no formulário).
Padrão Operacional P1
1. Segurança e Validação
Sempre valide entradas com esquema z.object({ e safeParse antes de processar. Verifique autorização dentro da ação. Veja Exemplo de Ação Segura.
2. Estados Pendentes
Use useActionState (React 19/Next.js 15+) para gerenciamento de estado e useFormStatus para estados de carregamento em botões.
Restrições
- Closures: Evite definir ações dentro de componentes para evitar sobrecarga de criptografia de closure oculta e bugs de serialização.
- Redirecionamento: Use
redirect()para navegação bem-sucedida; ele lança um erro que o Next.js captura para lidar com o redirecionamento.
Antipadrões
- Sem entradas de Server Action não validadas: Sempre valide com Zod antes de processar.
- Sem verificações de autorização ignoradas: Verifique sessão/usuário dentro de cada ação, não apenas no middleware.
- Sem ações definidas dentro de componentes: Defina em
actions.tspara evitar bugs de closure. - Sem
redirect()em try/catch:redirect()lança um erro; capturá-lo suprime o redirecionamento.