Forms

Core Idea

Pages Router lida com mutação de dados via API Routes: form no client faz fetch(POST) pra um endpoint em pages/api/*, que roda no servidor e pode usar env vars sensíveis com segurança.

Key Concepts

• API Route como handler: pages/api/submit.ts recebe req.body e devolve JSON; roda no servidor, então segredos (API keys) nunca vazam pro client.
• CORS same-origin por padrão: API Routes não especificam headers de CORS, só aceitam requests da própria origem.
• Validação client: HTML nativo (required, type="email") cobre o básico; validação de schema (Zod, Valibot) no servidor cobre o caso robusto, antes de mutar dado.
• Loading/error state: useState local pra isLoading/error, desabilitando o botão e mostrando mensagem durante o fetch.
• Redirect pós-mutação: res.redirect(307, ...) na API Route pra levar o usuário à página resultante (ex.: /post/${id}).

Code Examples

async function onSubmit(event: SubmitEvent<HTMLFormElement>) {
  event.preventDefault()
  setIsLoading(true)
  setError(null)
  try {
    const formData = new FormData(event.currentTarget)
    const response = await fetch('/api/submit', { method: 'POST', body: formData })
    if (!response.ok) throw new Error('Failed to submit the data. Please try again.')
    const data = await response.json()
  } catch (error) {
    setError(error.message)
  } finally {
    setIsLoading(false)
  }
}

• O que demonstra: padrão completo de submit com loading + tratamento de erro no client.

import { z } from 'zod'
const schema = z.object({ /* ... */ })

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const parsed = schema.parse(req.body)
}

• O que demonstra: validação de schema no servidor antes de processar o payload.

Anti-patterns

• Confiar só em validação client-side: HTML required/type é só UX; validação real de segurança precisa acontecer na API Route.
• Não checar response.ok: fetch não rejeita em erro HTTP (4xx/5xx), é preciso checar manualmente e lançar erro.

Key Takeaways

1. Toda mutação de dado sensível passa por API Route, nunca direto do client pro banco/serviço externo.
2. API Routes são same-origin por padrão, sem CORS configurado.
3. res.redirect(307, path) é o padrão pra navegar após mutação bem-sucedida.

Connects To

• ch295 Authentication: mesmo padrão de API Route protegida usado em login/sessão.