Ações de servidor para mutações de dados
Defina funções 'use server' para tratar mutações de formulários e invalide o cache com revalidatePath.
Ações de servidor para mutações de dados é uma aula grátis de React Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de React Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de React Academy inclui 4 aulas no total.
O que são ações do servidor
Ações do servidor são funções assíncronas marcadas com 'use server' que são executadas exclusivamente no servidor. Elas permitem enviar formulários e realizar mutações de dados sem escrever manipuladores de rotas de API.
Definindo uma ação do servidor
Adicione 'use server' no início da função (ou do arquivo) para criar uma ação do servidor. Ela só pode ser definida em Componentes de servidor ou em arquivos actions.ts dedicados.
// app/actions.ts
'use server';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
export async function createPost(formData: FormData) {
const title = formData.get('title') as string;
await db.post.create({ data: { title } });
revalidatePath('/blog');
redirect('/blog');
}Usando ações em formulários
Passe a função de ação para a propriedade action de um formulário. Sem onSubmit e sem manipulador de eventos — o Next.js serializa o formulário e chama a ação no servidor.
import { createPost } from './actions';
export default function NewPostForm() {
return (
<form action={createPost}>
<input name="title" placeholder="Post title" required />
<button type="submit">Create</button>
</form>
);
}Gancho useActionState
useActionState (React 19) envolve uma ação para acompanhar o estado pendente e receber o valor retornado pela ação no componente.
'use client';
import { useActionState } from 'react';
import { createPost } from './actions';
const initialState = { error: null };
export function PostForm() {
const [state, action, isPending] = useActionState(createPost, initialState);
return (
<form action={action}>
{state.error && <p className="error">{state.error}</p>}
<input name="title" />
<button disabled={isPending}>{isPending ? 'Creating...' : 'Create'}</button>
</form>
);
}Retornando erros de validação
Retorne um objeto da ação em vez de lançar um erro para enviar erros de validação de volta ao formulário por meio de useActionState.
export async function createPost(prevState: any, formData: FormData) {
'use server';
const title = formData.get('title') as string;
if (!title || title.length < 3) {
return { error: 'Title must be at least 3 characters' };
}
await db.post.create({ data: { title } });
revalidatePath('/blog');
redirect('/blog');
}Ações do servidor em manipuladores de eventos
Chame ações do servidor em manipuladores de eventos de Componentes de cliente (não apenas em ações de formulários), importando-as e chamando-as diretamente.
'use client';
import { deletePost } from './actions';
export function DeleteButton({ id }: { id: string }) {
return (
<button onClick={() => deletePost(id)}>
Delete
</button>
);
}Ações do servidor embutidas
Defina ações do servidor diretamente em um Componente de servidor usando uma função que contenha 'use server' — útil para manter a lógica de mutação junto ao componente.
export default function PostPage({ post }) {
async function updatePost(formData: FormData) {
'use server';
await db.post.update({ where: { id: post.id }, data: { title: formData.get('title') as string } });
revalidatePath(`/blog/${post.id}`);
}
return (
<form action={updatePost}>
<input name="title" defaultValue={post.title} />
<button type="submit">Save</button>
</form>
);
}useOptimistic com ações do servidor
Combine useOptimistic com ações do servidor para atualizar a interface imediatamente enquanto a ação é executada em segundo plano.
'use client';
import { useOptimistic } from 'react';
import { addItem } from './actions';
export function TodoList({ items }) {
const [optimisticItems, addOptimistic] = useOptimistic(items, (state, newItem) => [...state, newItem]);
return (
<form action={async (formData) => {
addOptimistic({ id: 'temp', text: formData.get('text') });
await addItem(formData);
}}>
<ul>{optimisticItems.map(i => <li key={i.id}>{i.text}</li>)}</ul>
<input name="text" /><button>Add</button>
</form>
);
}Considerações de segurança
As ações do servidor são endpoints POST nos bastidores. Sempre valide e higienize as entradas no servidor, verifique a autenticação e use proteção contra CSRF (o Next.js cuida disso automaticamente para a mesma origem).
Revalidando após mutações
Chame revalidatePath() ou revalidateTag() após uma mutação para limpar os caches relevantes, de modo que o próximo carregamento da página reflita a alteração.
Verificação rápida
Como passar uma ação do servidor para um formulário no roteador de aplicações do Next.js?
Recapitulação
Ações do servidor são funções assíncronas 'use server' que lidam com mutações no servidor. Conecte-as a formulários por meio da propriedade action, acompanhe o estado com useActionState, retorne erros em vez de lançá-los durante a validação e revalide os caches após as mutações.
Aprenda React com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 88
- Aulas
- 324
Perguntas Frequentes
A aula “Ações de servidor para mutações de dados” é grátis?
Sim — o texto completo de “Ações de servidor para mutações de dados” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de React Academy, atualize para CoddyKit PRO. O curso de React Academy inclui 4 aulas no total.
O que vou aprender em “Ações de servidor para mutações de dados”?
Defina funções 'use server' para tratar mutações de formulários e invalide o cache com revalidatePath. Você pratica React Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar React Academy?
Nenhuma experiência prévia é necessária. React Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Ações de servidor para mutações de dados”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de React Academy?
Sim. Cada aula de React Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- fetch() com opções de cache no Next.js
- unstable_cache e React cache()
- Regeneração estática incremental (ISR)
- Ações de servidor para mutações de dados