Funcionalidade em Next.js App Router com Server Actions

Prompt

Age como um engenheiro frontend sénior especializado em Next.js App Router, React Server Components e TypeScript estrito.

Preciso de implementar a funcionalidade «{{feature}}» numa aplicação Next.js {{next_version}}.
Camada de dados: {{data_layer}}.
Autenticação: {{auth}}.
Regras de negócio e campos do formulário: {{rules}}.

Entrega, por esta ordem:
1. A árvore de ficheiros dentro de `app/` e `lib/` (rotas, `page.tsx`, `loading.tsx`, `error.tsx`, componentes de cliente e de servidor), explicando o que é Server Component e o que é Client Component, e porquê.
2. Um esquema de validação Zod partilhado entre cliente e servidor, com mensagens de erro claras para o utilizador.
3. A Server Action completa (`'use server'`): verificação de sessão e de permissões, validação, escrita na base de dados, `revalidatePath` ou `revalidateTag`, e um objeto de resposta tipado `{ ok, errors, message }`.
4. O formulário com `useActionState` e `useFormStatus` (no Next.js 14 com React 18, usa `useFormState` de `react-dom` em vez de `useActionState`): erros por campo, botão desativado durante o envio e foco movido para o primeiro campo inválido.
5. Tratamento de erros: erros esperados vs. inesperados, o que fica registado em log e o que o utilizador vê.
6. Testes: testes unitários do esquema e da action (com a camada de dados simulada) e um teste end-to-end com Playwright para o caminho feliz.
7. Uma lista de verificação de segurança: CSRF, autorização no servidor, limites de tamanho do payload e dados sensíveis que nunca devem chegar ao cliente.

Restrições:
- TypeScript estrito, sem `any`.
- Não inventes nomes de tabelas nem variáveis de ambiente: usa [PREENCHER] se faltar alguma coisa.
- Se te faltar informação necessária para uma decisão importante, pergunta-me antes de escrever código.

Como utilizar

Exemplo de utilização

Exemplo de resultado

'use server';

import { revalidatePath } from 'next/cache';
import { auth } from '@/auth';
import { prisma } from '@/lib/prisma';
import { bookingSchema } from '@/lib/validation/booking';

export type ActionState = {
  ok: boolean;
  errors?: Partial<Record<'roomId' | 'start' | 'end', string[]>>;
  message?: string;
};

export async function createBooking(_prev: ActionState, formData: FormData): Promise<ActionState> {
  const session = await auth();
  if (!session?.user?.id) return { ok: false, message: 'Inicie sessão para reservar uma sala.' };

  const parsed = bookingSchema.safeParse(Object.fromEntries(formData));
  if (!parsed.success) return { ok: false, errors: parsed.error.flatten().fieldErrors };

  const { roomId, start, end } = parsed.data;
  const overlap = await prisma.booking.findFirst({
    where: { roomId, start: { lt: end }, end: { gt: start } },
  });
  if (overlap) return { ok: false, errors: { start: ['A sala já está reservada nesse horário.'] } };

  await prisma.booking.create({ data: { roomId, start, end, userId: session.user.id } });
  revalidatePath('/bookings');
  return { ok: true, message: 'Reserva criada.' };
}

Dados-chave

Categoria

Programação e desenvolvimento · Next.js

Tipo de resultado

Código

Nível

Avançado

Pensado para

ChatGPT, Claude e Microsoft Copilot

Verificado em

Pendente de verificação editorial

Variáveis

Funcionalidade, Versão do Next.js, Camada de dados, Autenticação e Regras e campos

Idioma

Português

Preço

Gratuito, sem registo

Atualizado

07/11/2026

Perguntas frequentes