React Academy · Aula

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.

Aula 4 de 412 etapas

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.

Grátis para começar

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

  1. fetch() com opções de cache no Next.js
  2. unstable_cache e React cache()
  3. Regeneração estática incremental (ISR)
  4. Ações de servidor para mutações de dados
← Voltar para React Academy