Server Actions

Q: Server Actions funcionam sem JavaScript habilitado no navegador?

Sim, quando usadas com , Server Actions suportam aprimoramento progressivo O formulário é enviado como uma requisição POST padrão quando o JS está desabilitado Isso não se aplica ao chamar actions de manipuladores de eventos como onClick

Q: Por que chamar redirect() dentro de um bloco try/catch não funciona?

redirect() lança um erro especial do Next.js internamente para disparar a navegação Envolver em try/catch engole esse erro e impede o redirect Sempre chame redirect() fora do bloco try/catch, após toda a outra lógica

Q: Que tipos de argumentos podem ser passados para uma Server Action?

Strings, números, booleanos, Date, Map, Set, arrays tipados e objetos/arrays simples FormData é suportado para submissões de formulário Você não pode passar nós DOM, instâncias de classe ou funções

Q: Qual a diferença entre useActionState e useTransition para Server Actions?

useActionState gerencia o estado do formulário e a validação, recebendo o estado anterior mais FormData useTransition apenas fornece um flag isPending e um wrapper startTransition Use useActionState quando precisar retornar erros ou status da action

Q: Como lidar com uploads de arquivos com Server Actions?

Use um com encType="multipart/form-data" ou construa FormData manualmente Você não pode usar JSON.stringify para dados de arquivo Acesse arquivos via formData.get("file") que retorna um objeto File

Mutate data from the server using "use server" functions -- no API routes needed.

Receita

Cartão de receita de referência rápida -- pronto para copiar e colar.

// app/actions.ts
"use server";
 
import { revalidatePath } from "next/cache";
 
export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;
 
  await db.post.create({ data: { title } });
  revalidatePath("/posts");
}

// app/posts/new/page.tsx (Server Component)
import { createPost } from "@/app/actions";
 
export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  );
}

Quando usar isso: Você precisa criar, atualizar ou excluir dados a partir de um formulário ou clique de botão sem escrever uma rota de API dedicada.

Exemplo de Trabalho

// app/actions/todo.ts
"use server";
 
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { db } from "@/lib/db";
 
export async function addTodo(formData: FormData) {
  const text = formData.get("text") as string;
 
  if (!text || text.trim().length === 0) {
    return { error: "Text is required" };
  }
 
  await db.todo.create({ data: { text: text.trim(), done: false } });
  revalidatePath("/todos");
}
 
export async function toggleTodo(id: string) {
  const todo = await db.todo.findUnique({ where: { id } });
  if (!todo) return { error: "Not found" };
 
  await db.todo.update({
    where: { id },
    data: { done: !todo.done },
  });
 
  revalidatePath("/todos");
}
 
export async function deleteTodo(id: string) {
  await db.todo.delete({ where: { id } });
  revalidatePath("/todos");
}

// app/todos/page.tsx (Server Component)
import { db } from "@/lib/db";
import { addTodo } from "@/app/actions/todo";
import { TodoItem } from "./todo-item";
 
export default async function TodosPage() {
  const todos = await db.todo.findMany({ orderBy: { createdAt: "desc" } });
 
  return (
    <main className="max-w-md mx-auto p-6">
      <h1 className="text-2xl font-bold mb-4">Todos</h1>
 
      <form action={addTodo} className="flex gap-2 mb-6">
        <input
          name="text"
          placeholder="What needs doing?"
          className="flex-1 border rounded px-3 py-2"
          required
        />
        <button
          type="submit"
          className="bg-blue-600 text-white px-4 py-2 rounded"
        >
          Add
        </button>
      </form>
 
      <ul className="space-y-2">
        {todos.map((todo) => (
          <TodoItem key={todo.id} todo={todo} />
        ))}
      </ul>
    </main>
  );
}

// app/todos/todo-item.tsx
"use client";
 
import { useTransition } from "react";
import { toggleTodo, deleteTodo } from "@/app/actions/todo";
 
type Todo = { id: string; text: string; done: boolean };
 
export function TodoItem({ todo }: { todo: Todo }) {
  const [isPending, startTransition] = useTransition();
 
  return (
    <li
      className={`flex items-center gap-3 p-2 border rounded ${
        isPending ? "opacity-50" : ""
      }`}
    >
      <input
        type="checkbox"
        checked={todo.done}
        onChange={() => startTransition(() => toggleTodo(todo.id))}
      />
      <span className={todo.done ? "line-through text-gray-400" : "flex-1"}>
        {todo.text}
      </span>
      <button
        onClick={() => startTransition(() => deleteTodo(todo.id))}
        className="text-red-500 text-sm"
      >
        Delete
      </button>
    </li>
  );
}

O que isso demonstra:

Definição de Server Actions em um arquivo "use server" separado
Vinculação de uma Server Action a um <form action> para aprimoramento progressivo
Chamada de Server Actions de Client Components via useTransition para UI pendente
Uso de revalidatePath para atualizar dados em cache após mutações

Análise Detalhada

Como Funciona

Uma Server Action é qualquer função async marcada com "use server" (no topo de um arquivo ou inline no corpo de uma função dentro de um Server Component).
Quando passada para um <form action>, o React envia os dados do formulário para o servidor e chama a função. Isso funciona mesmo sem JavaScript habilitado (aprimoramento progressivo).
Quando chamada de um manipulador de eventos de Client Component, a action é invocada como uma RPC -- o React serializa os argumentos, envia-os para o servidor e retorna o resultado.
Server Actions rodam em um contexto de servidor seguro. Elas podem acessar bancos de dados, variáveis de ambiente e sistemas de arquivos diretamente.
Após uma mutação, chame revalidatePath() ou revalidateTag() para invalidar dados em cache e disparar uma nova renderização.
Server Actions são requisições POST internamente. Elas são automaticamente protegidas contra CSRF por meio de verificações de mesma origem.

Variações

Server Action Inline (definida dentro de um Server Component):

export default function Page() {
  async function handleSubmit(formData: FormData) {
    "use server";
    const email = formData.get("email") as string;
    await subscribeToNewsletter(email);
  }
 
  return (
    <form action={handleSubmit}>
      <input name="email" type="email" required />
      <button type="submit">Subscribe</button>
    </form>
  );
}

Usando useActionState para estado e validação de formulário:

"use client";
 
import { useActionState } from "react";
import { createUser } from "@/app/actions/user";
 
type State = { error?: string; success?: boolean };
 
export function SignupForm() {
  const [state, formAction, isPending] = useActionState<State, FormData>(
    createUser,
    { error: undefined, success: false }
  );
 
  return (
    <form action={formAction}>
      <input name="email" type="email" required />
      {state.error && <p className="text-red-500">{state.error}</p>}
      <button type="submit" disabled={isPending}>
        {isPending ? "Creating..." : "Sign Up"}
      </button>
    </form>
  );
}

Atualizações otimistas com useOptimistic:

"use client";
 
import { useOptimistic, useTransition } from "react";
import { addTodo } from "@/app/actions/todo";
 
export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimistic] = useOptimistic(
    todos,
    (state, newTodo: string) => [
      ...state,
      { id: crypto.randomUUID(), text: newTodo, done: false },
    ]
  );
  const [, startTransition] = useTransition();
 
  return (
    <form
      action={(formData) => {
        const text = formData.get("text") as string;
        startTransition(async () => {
          addOptimistic(text);
          await addTodo(formData);
        });
      }}
    >
      <input name="text" required />
      <button type="submit">Add</button>
      <ul>
        {optimisticTodos.map((t) => (
          <li key={t.id}>{t.text}</li>
        ))}
      </ul>
    </form>
  );
}

Notas de TypeScript

// Assinatura da Server Action ao ser usada com <form action>
export async function myAction(formData: FormData): Promise<void> {
  "use server";
  // ...
}
 
// Server Action com useActionState -- recebe o estado anterior + formData
export async function myAction(
  prevState: { error?: string },
  formData: FormData
): Promise<{ error?: string }> {
  "use server";
  // ...
}
 
// Server Action chamada diretamente (não de um formulário)
export async function deleteItem(id: string): Promise<{ success: boolean }> {
  "use server";
  // ...
}

Armadilhas

Argumentos devem ser serializáveis -- Você não pode passar nós DOM, instâncias de classe ou funções para uma Server Action. Correção: Passe apenas strings, números, booleanos, FormData, objetos simples, arrays, Date, Map, Set ou arrays tipados.
revalidatePath não funciona dentro de try/catch com redirect -- Chamar redirect() lança um erro especial do Next.js. Se você o envolver em try/catch, o redirect será engolido. Correção: Chame redirect() fora do bloco try/catch, após toda a outra lógica.
Server Actions são apenas POST -- Elas não podem ser usadas para requisições GET ou leituras idempotentes. Correção: Use um fetch regular ou Server Component para ler dados.
Uploads de arquivos precisam de FormData -- Você não pode usar JSON.stringify para arquivos. Correção: Use um <form> com encType="multipart/form-data" ou construa FormData manualmente no cliente.
Sem acesso aos cabeçalhos da requisição por padrão -- Server Actions não recebem automaticamente cookies ou cabeçalhos. Correção: Use cookies() e headers() de next/headers dentro do corpo da action.
Variáveis de closure são serializadas -- Se você definir uma action inline "use server" que fecha sobre uma variável, essa variável é serializada e enviada com a action. Correção: Esteja ciente de dados sensíveis em closures; valide todas as entradas no servidor.

Alternativas

Alternativa	Use Quando	Não Use Quando
Route Handlers (API routes)	Você precisa de um endpoint REST para clientes externos ou webhooks	Você apenas muta dados da sua própria UI
SWR `mutate` + API route	Você precisa de invalidação de cache instantânea no cliente com SWR	Você quer aprimoramento progressivo
tRPC	Você quer segurança de tipo ponta a ponta com uma camada RPC dedicada	Você quer manter as coisas nativas do framework
`fetch` de Client Component	Você precisa de controle total sobre o manuseio de requisição/resposta	Server Actions já cobrem seu caso de uso

FAQs

O que a diretiva `"use server"` realmente faz?

Marca funções assíncronas como Server Actions que rodam exclusivamente no servidor
Pode ser colocada no topo de um arquivo (marca todas as exportações) ou inline no corpo de uma função dentro de um Server Component
O React serializa os argumentos, envia-os para o servidor e chama a função como uma RPC

Server Actions funcionam sem JavaScript habilitado no navegador?

Sim, quando usadas com <form action>, Server Actions suportam aprimoramento progressivo
O formulário é enviado como uma requisição POST padrão quando o JS está desabilitado
Isso não se aplica ao chamar actions de manipuladores de eventos como onClick

Por que chamar `redirect()` dentro de um bloco try/catch não funciona?

redirect() lança um erro especial do Next.js internamente para disparar a navegação
Envolver em try/catch engole esse erro e impede o redirect
Sempre chame redirect() fora do bloco try/catch, após toda a outra lógica

Como mostrar um estado pendente quando uma Server Action está rodando?

"use client";
import { useTransition } from "react";
import { deleteItem } from "@/app/actions";
 
function DeleteButton({ id }: { id: string }) {
  const [isPending, startTransition] = useTransition();
  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => deleteItem(id))}
    >
      {isPending ? "Deleting..." : "Delete"}
    </button>
  );
}

Que tipos de argumentos podem ser passados para uma Server Action?

Strings, números, booleanos, Date, Map, Set, arrays tipados e objetos/arrays simples
FormData é suportado para submissões de formulário
Você não pode passar nós DOM, instâncias de classe ou funções

Qual a diferença entre `useActionState` e `useTransition` para Server Actions?

useActionState gerencia o estado do formulário e a validação, recebendo o estado anterior mais FormData
useTransition apenas fornece um flag isPending e um wrapper startTransition
Use useActionState quando precisar retornar erros ou status da action

Como tipar uma Server Action que é usada com `useActionState`?

// A action recebe prevState como seu primeiro argumento
export async function createUser(
  prevState: { error?: string },
  formData: FormData
): Promise<{ error?: string }> {
  "use server";
  const email = formData.get("email") as string;
  if (!email) return { error: "Email is required" };
  // ...
  return {};
}

Como Server Actions são protegidas contra ataques CSRF?

Server Actions são requisições POST internamente
Next.js aplica automaticamente verificações de mesma origem
Nenhuma configuração adicional de token CSRF é necessária

É possível acessar cookies ou cabeçalhos dentro de uma Server Action?

Server Actions não recebem automaticamente cookies ou cabeçalhos
Importe e chame cookies() e headers() de next/headers dentro do corpo da action
Ambos são assíncronos no Next.js 15+ e devem ser aguardados (await)

O que acontece se uma action inline `"use server"` fechar sobre uma variável sensível?

A variável sobre a qual a closure foi feita é serializada e enviada para o cliente como parte da referência da action
Isso pode expor dados sensíveis não intencionalmente
Sempre valide todas as entradas no servidor e evite fechar sobre segredos

Como implementar atualizações otimistas com Server Actions?

"use client";
import { useOptimistic, useTransition } from "react";
 
function TodoList({ todos }: { todos: Todo[] }) {
  const [optimistic, addOptimistic] = useOptimistic(
    todos,
    (state, newText: string) => [
      ...state,
      { id: crypto.randomUUID(), text: newText, done: false },
    ]
  );
  // use addOptimistic dentro de startTransition antes de aguardar a action
}

Como lidar com uploads de arquivos com Server Actions?

Use um <form> com encType="multipart/form-data" ou construa FormData manualmente
Você não pode usar JSON.stringify para dados de arquivo
Acesse arquivos via formData.get("file") que retorna um objeto File

Relacionados

Fetching -- Lendo dados em Server Components
Revalidation -- Atualizando dados em cache após mutações
Cookies & Headers -- Acessando o contexto da requisição em actions
Client Components -- Usando useTransition com actions

Receita

Cartão de receita de referência rápida -- pronto para copiar e colar.

// app/actions.ts
"use server";
 
import { revalidatePath } from "next/cache";
 
export async function createPost(formData: FormData) {
  const title = formData.get("title") as string;
 
  await db.post.create({ data: { title } });
  revalidatePath("/posts");
}

// app/posts/new/page.tsx (Server Component)
import { createPost } from "@/app/actions";
 
export default function NewPostPage() {
  return (
    <form action={createPost}>
      <input name="title" required />
      <button type="submit">Create</button>
    </form>
  );
}

Quando usar isso: Você precisa criar, atualizar ou excluir dados a partir de um formulário ou clique de botão sem escrever uma rota de API dedicada.

Exemplo de Trabalho

// app/actions/todo.ts
"use server";
 
import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { db } from "@/lib/db";
 
export async function addTodo(formData: FormData) {
  const text = formData.get("text") as string;
 
  if (!text || text.trim().length === 0) {
    return { error: "Text is required" };
  }
 
  await db.todo.create({ data: { text: text.trim(), done: false } });
  revalidatePath("/todos");
}
 
export async function toggleTodo(id: string) {
  const todo = await db.todo.findUnique({ where: { id } });
  if (!todo) return { error: "Not found" };
 
  await db.todo.update({
    where: { id },
    data: { done: !todo.done },
  });
 
  revalidatePath("/todos");
}
 
export async function deleteTodo(id: string) {
  await db.todo.delete({ where: { id } });
  revalidatePath("/todos");
}

// app/todos/page.tsx (Server Component)
import { db } from "@/lib/db";
import { addTodo } from "@/app/actions/todo";
import { TodoItem } from "./todo-item";
 
export default async function TodosPage() {
  const todos = await db.todo.findMany({ orderBy: { createdAt: "desc" } });
 
  return (
    <main className="max-w-md mx-auto p-6">
      <h1 className="text-2xl font-bold mb-4">Todos</h1>
 
      <form action={addTodo} className="flex gap-2 mb-6">
        <input
          name="text"
          placeholder="What needs doing?"
          className="flex-1 border rounded px-3 py-2"
          required
        />
        <button
          type="submit"
          className="bg-blue-600 text-white px-4 py-2 rounded"
        >
          Add
        </button>
      </form>
 
      <ul className="space-y-2">
        {todos.map((todo) => (
          <TodoItem key={todo.id} todo={todo} />
        ))}
      </ul>
    </main>
  );
}

// app/todos/todo-item.tsx
"use client";
 
import { useTransition } from "react";
import { toggleTodo, deleteTodo } from "@/app/actions/todo";
 
type Todo = { id: string; text: string; done: boolean };
 
export function TodoItem({ todo }: { todo: Todo }) {
  const [isPending, startTransition] = useTransition();
 
  return (
    <li
      className={`flex items-center gap-3 p-2 border rounded ${
        isPending ? "opacity-50" : ""
      }`}
    >
      <input
        type="checkbox"
        checked={todo.done}
        onChange={() => startTransition(() => toggleTodo(todo.id))}
      />
      <span className={todo.done ? "line-through text-gray-400" : "flex-1"}>
        {todo.text}
      </span>
      <button
        onClick={() => startTransition(() => deleteTodo(todo.id))}
        className="text-red-500 text-sm"
      >
        Delete
      </button>
    </li>
  );
}

O que isso demonstra:

Definição de Server Actions em um arquivo "use server" separado
Vinculação de uma Server Action a um <form action> para aprimoramento progressivo
Chamada de Server Actions de Client Components via useTransition para UI pendente
Uso de revalidatePath para atualizar dados em cache após mutações

Análise Detalhada

Como Funciona

Uma Server Action é qualquer função async marcada com "use server" (no topo de um arquivo ou inline no corpo de uma função dentro de um Server Component).
Quando passada para um <form action>, o React envia os dados do formulário para o servidor e chama a função. Isso funciona mesmo sem JavaScript habilitado (aprimoramento progressivo).
Quando chamada de um manipulador de eventos de Client Component, a action é invocada como uma RPC -- o React serializa os argumentos, envia-os para o servidor e retorna o resultado.
Server Actions rodam em um contexto de servidor seguro. Elas podem acessar bancos de dados, variáveis de ambiente e sistemas de arquivos diretamente.
Após uma mutação, chame revalidatePath() ou revalidateTag() para invalidar dados em cache e disparar uma nova renderização.
Server Actions são requisições POST internamente. Elas são automaticamente protegidas contra CSRF por meio de verificações de mesma origem.

Variações

Server Action Inline (definida dentro de um Server Component):

export default function Page() {
  async function handleSubmit(formData: FormData) {
    "use server";
    const email = formData.get("email") as string;
    await subscribeToNewsletter(email);
  }
 
  return (
    <form action={handleSubmit}>
      <input name="email" type="email" required />
      <button type="submit">Subscribe</button>
    </form>
  );
}

Usando useActionState para estado e validação de formulário:

"use client";
 
import { useActionState } from "react";
import { createUser } from "@/app/actions/user";
 
type State = { error?: string; success?: boolean };
 
export function SignupForm() {
  const [state, formAction, isPending] = useActionState<State, FormData>(
    createUser,
    { error: undefined, success: false }
  );
 
  return (
    <form action={formAction}>
      <input name="email" type="email" required />
      {state.error && <p className="text-red-500">{state.error}</p>}
      <button type="submit" disabled={isPending}>
        {isPending ? "Creating..." : "Sign Up"}
      </button>
    </form>
  );
}

Atualizações otimistas com useOptimistic:

"use client";
 
import { useOptimistic, useTransition } from "react";
import { addTodo } from "@/app/actions/todo";
 
export function TodoList({ todos }: { todos: Todo[] }) {
  const [optimisticTodos, addOptimistic] = useOptimistic(
    todos,
    (state, newTodo: string) => [
      ...state,
      { id: crypto.randomUUID(), text: newTodo, done: false },
    ]
  );
  const [, startTransition] = useTransition();
 
  return (
    <form
      action={(formData) => {
        const text = formData.get("text") as string;
        startTransition(async () => {
          addOptimistic(text);
          await addTodo(formData);
        });
      }}
    >
      <input name="text" required />
      <button type="submit">Add</button>
      <ul>
        {optimisticTodos.map((t) => (
          <li key={t.id}>{t.text}</li>
        ))}
      </ul>
    </form>
  );
}

Notas de TypeScript

// Assinatura da Server Action ao ser usada com <form action>
export async function myAction(formData: FormData): Promise<void> {
  "use server";
  // ...
}
 
// Server Action com useActionState -- recebe o estado anterior + formData
export async function myAction(
  prevState: { error?: string },
  formData: FormData
): Promise<{ error?: string }> {
  "use server";
  // ...
}
 
// Server Action chamada diretamente (não de um formulário)
export async function deleteItem(id: string): Promise<{ success: boolean }> {
  "use server";
  // ...
}

Armadilhas

Argumentos devem ser serializáveis -- Você não pode passar nós DOM, instâncias de classe ou funções para uma Server Action. Correção: Passe apenas strings, números, booleanos, FormData, objetos simples, arrays, Date, Map, Set ou arrays tipados.
revalidatePath não funciona dentro de try/catch com redirect -- Chamar redirect() lança um erro especial do Next.js. Se você o envolver em try/catch, o redirect será engolido. Correção: Chame redirect() fora do bloco try/catch, após toda a outra lógica.
Server Actions são apenas POST -- Elas não podem ser usadas para requisições GET ou leituras idempotentes. Correção: Use um fetch regular ou Server Component para ler dados.
Uploads de arquivos precisam de FormData -- Você não pode usar JSON.stringify para arquivos. Correção: Use um <form> com encType="multipart/form-data" ou construa FormData manualmente no cliente.
Sem acesso aos cabeçalhos da requisição por padrão -- Server Actions não recebem automaticamente cookies ou cabeçalhos. Correção: Use cookies() e headers() de next/headers dentro do corpo da action.
Variáveis de closure são serializadas -- Se você definir uma action inline "use server" que fecha sobre uma variável, essa variável é serializada e enviada com a action. Correção: Esteja ciente de dados sensíveis em closures; valide todas as entradas no servidor.

Alternativas

Alternativa	Use Quando	Não Use Quando
Route Handlers (API routes)	Você precisa de um endpoint REST para clientes externos ou webhooks	Você apenas muta dados da sua própria UI
SWR `mutate` + API route	Você precisa de invalidação de cache instantânea no cliente com SWR	Você quer aprimoramento progressivo
tRPC	Você quer segurança de tipo ponta a ponta com uma camada RPC dedicada	Você quer manter as coisas nativas do framework
`fetch` de Client Component	Você precisa de controle total sobre o manuseio de requisição/resposta	Server Actions já cobrem seu caso de uso

FAQs

O que a diretiva `"use server"` realmente faz?

Marca funções assíncronas como Server Actions que rodam exclusivamente no servidor
Pode ser colocada no topo de um arquivo (marca todas as exportações) ou inline no corpo de uma função dentro de um Server Component
O React serializa os argumentos, envia-os para o servidor e chama a função como uma RPC

Server Actions funcionam sem JavaScript habilitado no navegador?

Sim, quando usadas com <form action>, Server Actions suportam aprimoramento progressivo
O formulário é enviado como uma requisição POST padrão quando o JS está desabilitado
Isso não se aplica ao chamar actions de manipuladores de eventos como onClick

Por que chamar `redirect()` dentro de um bloco try/catch não funciona?

redirect() lança um erro especial do Next.js internamente para disparar a navegação
Envolver em try/catch engole esse erro e impede o redirect
Sempre chame redirect() fora do bloco try/catch, após toda a outra lógica

Como mostrar um estado pendente quando uma Server Action está rodando?

"use client";
import { useTransition } from "react";
import { deleteItem } from "@/app/actions";
 
function DeleteButton({ id }: { id: string }) {
  const [isPending, startTransition] = useTransition();
  return (
    <button
      disabled={isPending}
      onClick={() => startTransition(() => deleteItem(id))}
    >
      {isPending ? "Deleting..." : "Delete"}
    </button>
  );
}

Que tipos de argumentos podem ser passados para uma Server Action?

Strings, números, booleanos, Date, Map, Set, arrays tipados e objetos/arrays simples
FormData é suportado para submissões de formulário
Você não pode passar nós DOM, instâncias de classe ou funções

Qual a diferença entre `useActionState` e `useTransition` para Server Actions?

useActionState gerencia o estado do formulário e a validação, recebendo o estado anterior mais FormData
useTransition apenas fornece um flag isPending e um wrapper startTransition
Use useActionState quando precisar retornar erros ou status da action

Como tipar uma Server Action que é usada com `useActionState`?

// A action recebe prevState como seu primeiro argumento
export async function createUser(
  prevState: { error?: string },
  formData: FormData
): Promise<{ error?: string }> {
  "use server";
  const email = formData.get("email") as string;
  if (!email) return { error: "Email is required" };
  // ...
  return {};
}

Como Server Actions são protegidas contra ataques CSRF?

Server Actions são requisições POST internamente
Next.js aplica automaticamente verificações de mesma origem
Nenhuma configuração adicional de token CSRF é necessária

É possível acessar cookies ou cabeçalhos dentro de uma Server Action?

Server Actions não recebem automaticamente cookies ou cabeçalhos
Importe e chame cookies() e headers() de next/headers dentro do corpo da action
Ambos são assíncronos no Next.js 15+ e devem ser aguardados (await)

O que acontece se uma action inline `"use server"` fechar sobre uma variável sensível?

A variável sobre a qual a closure foi feita é serializada e enviada para o cliente como parte da referência da action
Isso pode expor dados sensíveis não intencionalmente
Sempre valide todas as entradas no servidor e evite fechar sobre segredos

Como implementar atualizações otimistas com Server Actions?

"use client";
import { useOptimistic, useTransition } from "react";
 
function TodoList({ todos }: { todos: Todo[] }) {
  const [optimistic, addOptimistic] = useOptimistic(
    todos,
    (state, newText: string) => [
      ...state,
      { id: crypto.randomUUID(), text: newText, done: false },
    ]
  );
  // use addOptimistic dentro de startTransition antes de aguardar a action
}

Como lidar com uploads de arquivos com Server Actions?

Use um <form> com encType="multipart/form-data" ou construa FormData manualmente
Você não pode usar JSON.stringify para dados de arquivo
Acesse arquivos via formData.get("file") que retorna um objeto File

Relacionados

Fetching -- Lendo dados em Server Components
Revalidation -- Atualizando dados em cache após mutações
Cookies & Headers -- Acessando o contexto da requisição em actions
Client Components -- Usando useTransition com actions

Server Actions

Buscar na documentação

Server Actions