# React: instruções para agentes de IA

- Página: Padrões de componentes React e gerenciamento de estado (https://brasilgeo.ai/leadlovers2026/design/react/)
- Revisado em: 2026-11-16
- JSON com o mesmo conteúdo: https://brasilgeo.ai/leadlovers2026/design/react/agentes.json
- Índice dos guias de Design para agentes: https://brasilgeo.ai/leadlovers2026/design/llms.txt
- Esquema: design-guia-para-agentes/v1

Decide como escrever e revisar React em 2026: cinco padrões de componente com sinal de reprovação, o lugar de cada tipo de estado (local, derivado, cliente, servidor, URL), o critério oficial para dispensar useEffect, formulários sem re-render por tecla e a versão mínima de Next.js por segurança. Resultado: componente atual, sem estado duplicado e sem memoização ou efeito desnecessários.

## Quando consultar

- Escrever ou revisar componente, tela, formulário ou lista em React ou Next.js.
- Decidir onde guardar um dado: useState, Context, Zustand, Jotai, TanStack Query ou URL.
- Adicionar useEffect, useMemo ou useCallback.
- Buscar dado de servidor, enviar formulário ou mostrar resposta em streaming.
- Montar filtro, aba ou busca que o usuário compartilha por link.
- Criar tabela longa, lista reordenável ou animação ligada à rolagem.
- Conferir versões e segurança de uma entrega de outro agente.

## Regras

- **REA-01** (obrigatória). Antes de criar estado, classifique o dado (local, derivado, cliente compartilhado, servidor ou URL) e use a ferramenta daquele lugar. Por quê: Errar a classe vira reescrita da camada de dados. Sintoma: duas telas com saldos diferentes.
- **REA-02** (obrigatória). Calcule dado derivado (total, lista filtrada) no render. Nunca o guarde em useState. Por quê: Duas fontes de verdade divergem na primeira alteração.
- **REA-03** (obrigatória). Todo useEffect nomeia o sistema externo que sincroniza (widget fora do React, rede, DOM do navegador). Sem sistema externo, remova o Effect. Por quê: Critério oficial de 'You Might Not Need an Effect'.
- **REA-04** (obrigatória). Lógica causada por interação vai no event handler. Só a causada por o componente aparecer na tela vai no Effect. Por quê: No Effect já se perdeu qual interação ocorreu.
- **REA-05** (obrigatória). Todo Effect que cria listener, observer, timer, frame ou AbortController devolve limpeza que desfaz cada item criado. Por quê: O StrictMode monta, desmonta e remonta. Sem limpeza a animação roda em dobro e a memória sobe.
- **REA-06** (obrigatória). Dado de servidor fica no cache do TanStack Query (cliente) ou do framework (servidor), com invalidação explícita. Nunca copie para useState ou Zustand. Por quê: A cópia cria dois números do mesmo dado.
- **REA-07** (obrigatória). Dê a cada consulta uma queryKey própria, com os parâmetros dentro. Por quê: Mesma queryKey em consultas diferentes mostra o dado de uma tela na outra.
- **REA-08** (obrigatória). Em lista, key vem do id do dado. Nunca índice nem Math.random(). Trate a lista vazia. Por quê: Índice 'leva a bugs sutis'. Key aleatória recria o DOM e perde o que o usuário digitou.
- **REA-09** (obrigatória). Revise cada componente pelo padrão e reprove pelo sinal: props com mais de meia dúzia e crescendo; children com invólucro que recebe props do que carrega; DOM alterado à mão em vez de useState; key de índice ou aleatória, ou lista vazia sem tratamento; erro só em cor ou só após o envio. Por quê: Os cinco padrões (props, children, useState, lista com key, campo controlado) cobrem a maioria das telas.
- **REA-10** (obrigatória). Campo controlado mostra o erro em texto, na borda e com aria-invalid, sem esperar o envio. Por quê: Erro só em cor reprova o padrão.
- **REA-11** (recomendada). Em código novo, deixe a memoização ao React Compiler 1.0 e reserve useMemo e useCallback para controle preciso. Pergunte se o projeto ativou o compilador antes de aceitar memoização manual em tudo. Por quê: Recomendação oficial. Em código existente, mantenha ou teste antes de remover.
- **REA-12** (obrigatória). Filtro, aba, ordenação, página e busca moram na URL com nuqs. Envolva a raiz no NuqsAdapter do framework. Por quê: O link reproduz a tela. Sem o adapter o valor nunca chega ao endereço.
- **REA-13** (recomendada). Cliente compartilhado de alta frequência vai para Zustand (seletores) ou Jotai (granular). Context só para valor estável. Seletor Zustand que monta objeto exige useShallow. Por quê: Context re-renderiza todo consumidor. Seletor com referência nova gera 'Maximum update depth exceeded'.
- **REA-14** (recomendada). Formulário com 3 campos ou mais, ou lento no celular, usa react-hook-form com mode "onTouched". Campo único usa useState. Por quê: register usa ref (não controlado). O modo onChange valida a cada tecla, com 'impacto significativo de performance'.
- **REA-15** (obrigatória). Chame useFormStatus em componente filho dentro do <form>, nunca no que renderiza o form. Use useOptimistic só para curtir, marcar e arrastar, nunca para pagamento. Por quê: useFormStatus reporta o form pai. useOptimistic reverte sozinho na falha.
- **REA-16** (obrigatória). Escreva "use client" só nos arquivos de fronteira, no topo. Props que cruzam a fronteira são serializáveis. Por quê: A diretiva em todo arquivo manda o componente inteiro ao navegador.
- **REA-17** (obrigatória). Exija Next.js 16.2.11 ou mais novo (15.5.21 na linha 15). Server Function autentica e autoriza antes de operação sensível, lê credencial de cookie ou header e devolve só o que a tela usa. Por quê: O July 2026 Security Release corrigiu 9 CVEs, incluindo DoS e SSRF em Server Actions.
- **REA-18** (obrigatória). No Next.js 16, use proxy.ts (não middleware.ts novo), await em params, cookies() e headers(), e Cache Components com "use cache". Evite experimental.ppr. Por quê: A forma antiga é Next de 2024.
- **REA-19** (obrigatória). Lista longa sobe a escada um degrau por vez, com medição: tabela nativa, virtualização, fatias pelo servidor, imagem. Com TanStack Table v9, declare só as features usadas em tableFeatures() e recuse useLegacyTable. Por quê: useLegacyTable inclui tudo e pesa mais que a v8. Virtualização quebra Ctrl+F e teclado.
- **REA-20** (recomendada). Teste com getByRole e simule a rede com MSW para afirmar carregando, falhou e chegou. Por quê: Se o papel não acha o elemento, a tela pode ser inacessível.
- **REA-21** (obrigatória). Operação cancelável: um AbortController por pedido, guardado como pedido ativo. Compare com o ativo antes de cada setState e passe o signal ao fetch. Por quê: O controller interrompe a espera. A comparação protege a tela se a fonte ignorar o abort.
- **REA-22** (obrigatória). Animação ligada à rolagem usa só transform e opacity, atraso de 0,5 a 1 s para conteúdo e versão parada sob prefers-reduced-motion. will-change só no que se move sempre. Por quê: Acima de 2 s parece desligada do gesto. 100 elementos com will-change derrubam um celular.
- **REA-23** (obrigatória). Widget complexo (combobox, seletor de data, tabela navegável) vem de biblioteca de acessibilidade (React Aria Components, Base UI, Radix), nunca de div com onClick. Por quê: Elas trazem papel ARIA, foco e teclado prontos.
- **REA-24** (obrigatória). Cite só versões que existem: React 19.x, Next 16.x, TanStack Query v5. Por quê: React 20 e TanStack Query v6 não existem.

## Decisões rápidas

| Situação | Escolha | Evite |
| --- | --- | --- |
| Dado de um componente só (aba aberta, campo aberto) | useState ou useReducer | Biblioteca global |
| Dado calculável de outros (total, lista filtrada) | Calcular no render | Guardar em useState |
| Cliente compartilhado, baixa frequência (tema, sessão, modal) | Context com useReducer | Store pesado |
| Cliente compartilhado, alta frequência (carrinho) | Zustand com seletores e useShallow | Context, que re-renderiza em cascata |
| Formulário ou editor complexo com grão fino | Jotai, por átomos | Store monolítico |
| Filtro, aba, ordenação, página ou busca | URL com nuqs | useState que some ao recarregar |
| Dado do backend (produtos, perfil) | TanStack Query no cliente ou cache do framework no servidor | Cópia em useState ou Zustand |
| Fonte externa (tamanho da janela, store próprio) | useSyncExternalStore | useEffect improvisado |
| Atualização que disputa com a digitação | useTransition (pendência) ou useDeferredValue (versão derivada adiada) |  |
| Context grande com cascata | 1) dividir por frequência, 2) estabilizar value com useMemo, 3) store com seletores |  |
| Dado que muda várias vezes por segundo | Fora do ciclo de render (motor próprio) ou sinais reativos, verificando a convivência com o Compiler | setState a cada mensagem |

## Números de referência

| Valor | Para quê | Fonte |
| --- | --- | --- |
| React 19.3, 9/9/2026 (19.3.1 em 14/10/2026) | Versão estável a assumir. Traz ViewTransition estável, Fragment Refs e Context em Server Components | blog do React |
| React Compiler 1.0, 7/10/2025 | Memoização automática em build | blog do React |
| Next.js 16 (21/10/2025); 16.4.2 em 15/10/2026 | Turbopack padrão, proxy.ts, Cache Components | blog do Next.js |
| Next.js 16.2.11 ou 15.5.21 | Piso de segurança (9 CVEs, release de 20/7/2026) | July 2026 Security Release |
| TanStack Query 5.101.4; react-hook-form 7.85.0; nuqs 2.9.6; Zustand 5.0.15; Jotai 2.20.2 | Versões estáveis de 18/8/2026. Reconfira antes de citar | registro npm |
| TanStack Table 9.1.2 (v9 estável em 4/8/2026); TanStack Virtual 3.14.21 | Tabela com features declaradas e virtualização | registro npm |
| TanStack Query 68% de uso e 97% de retenção; Zustand 50% e 94%; Jotai 18% e 92% | Adoção das opções de estado | State of React 2025 |
| 0,5 a 1 s (conteúdo); 1,5 a 2 s (fundo) | Atraso de scrub na rolagem | guias Annnimate |
| Acima de 2.000 linhas | Passa a virtualizar com @tanstack/react-virtual (aria-rowcount e aria-rowindex) | prompt de tabela longa |

## Erros comuns e a correção

- Erro: useEffect que lê estado, calcula e grava outro estado. Corrija: Calcule no topo do componente, durante o render.
- Erro: Dado de servidor copiado para useState ou Zustand. Corrija: Mantenha no cache do TanStack Query.
- Erro: useMemo e useCallback em todo componente novo. Corrija: Confie no React Compiler.
- Erro: bg-${cor}-500 ou 'text-' + tom (o Tailwind só gera classes que vê inteiras) Corrija: Mapa estático de variantes com as strings completas.
- Erro: useFormStatus no componente que renderiza o form. Corrija: Mova para um botão filho dentro do <form>.
- Erro: middleware.ts novo, params síncrono, experimental.ppr. Corrija: proxy.ts, await params, Cache Components.
- Erro: Estado de streaming gravado a cada token. Corrija: Parcial em contêiner aria-live="polite" e estado final em um commit único.
- Erro: use() dentro de try-catch. Corrija: Suspense trata a pendente e o Error Boundary a rejeitada. Para Error Boundary use react-error-boundary.

## Padrões de código

### Estado na URL com nuqs

Filtro, busca e página que o link deve reproduzir.

```tsx
"use client";
import { useQueryState, parseAsInteger } from "nuqs";

// Exige <NuqsAdapter> na raiz do app.
export function Filtros() {
  const [busca, setBusca] = useQueryState("busca", { defaultValue: "" });
  const [pagina, setPagina] = useQueryState("pagina", parseAsInteger.withDefault(1));
  return (
    <>
      <input value={busca} onChange={(e) => { setBusca(e.target.value); setPagina(1); }} />
      <button onClick={() => setPagina((p) => p + 1)}>Página {pagina}</button>
    </>
  );
}
```

### Operação cancelável

Streaming ou requisição que o usuário cancela e repete.

```tsx
import { useEffect, useRef, useState } from "react";

type Tarefa = { controlador: AbortController };

export function useOperacao(fonte: (signal: AbortSignal) => AsyncIterable<string>) {
  const [texto, setTexto] = useState("");
  const ativo = useRef<Tarefa | null>(null);
  // Sair da tela aborta o pedido pendente.
  useEffect(() => () => { ativo.current?.controlador.abort(); ativo.current = null; }, []);

  async function executar() {
    ativo.current?.controlador.abort();
    const tarefa = { controlador: new AbortController() };
    ativo.current = tarefa; // a identidade do objeto faz o papel do serial
    setTexto("");
    try {
      for await (const t of fonte(tarefa.controlador.signal)) {
        if (ativo.current !== tarefa) return; // pedido antigo: descarta
        setTexto((x) => x + t);
      }
    } catch { /* cancelado ou falhou: o texto parcial fica */ }
    finally { if (ativo.current === tarefa) ativo.current = null; }
  }
  return { texto, executar, cancelar: () => ativo.current?.controlador.abort() };
}
```

## Checklist antes de entregar

- [ ] A entrega assume React 19.2 ou 19.3 e Next.js 16.2.11 ou mais novo, sem React 20 nem TanStack Query v6.
- [ ] Cada componente cabe num dos cinco padrões e não tem o sinal de reprovação dele.
- [ ] Cada estado tem lugar declarado: local, derivado, cliente, servidor ou URL.
- [ ] Nenhum dado derivado está em useState e nenhum dado de servidor está duplicado em store local.
- [ ] Todo useEffect nomeia o sistema externo e devolve limpeza do que criou.
- [ ] Sem useMemo e useCallback em massa: o Compiler está ativo ou há motivo escrito.
- [ ] Listas usam key de id e tratam o caso vazio.
- [ ] Filtro, aba e busca estão na URL, com NuqsAdapter na raiz.
- [ ] "use client" só nas fronteiras, Server Functions autenticam, e existe proxy.ts em vez de middleware.ts novo.
- [ ] Formulário de 3 campos ou mais usa mode onTouched, com erros em texto e aria-invalid.
- [ ] Testes localizam por getByRole e a rede é simulada com MSW.
- [ ] Animação respeita prefers-reduced-motion e o conteúdo aparece sem JavaScript.

## Ferramentas citadas

- **React Compiler 1.0**: Memoização automática em build.
- **TanStack Query 5**: Cache de dado de servidor.
- **nuqs 2**: Estado na URL.
- **react-hook-form 7**: Formulário não controlado.
- **React Aria Components, Base UI, Radix**: Widgets acessíveis prontos.
- **Zustand 5 e Jotai 2**: Estado de cliente de alta frequência.

## Onde aprofundar na página

- [Cinco padrões e sinal de reprovação](https://brasilgeo.ai/leadlovers2026/design/react/#padroes)
- [React Compiler](https://brasilgeo.ai/leadlovers2026/design/react/#compilador)
- [Onde mora cada estado](https://brasilgeo.ai/leadlovers2026/design/react/#estado)
- [Quando o useEffect sobra](https://brasilgeo.ai/leadlovers2026/design/react/#effect)
- [Dado de servidor e hooks de formulário do React 19](https://brasilgeo.ai/leadlovers2026/design/react/#servidor)
- [Estado na URL](https://brasilgeo.ai/leadlovers2026/design/react/#url)
- [Next.js 16 e segurança](https://brasilgeo.ai/leadlovers2026/design/react/#next)
- [Tela de dados e TanStack Table v9](https://brasilgeo.ai/leadlovers2026/design/react/#tabelas)
- [Testes e MSW](https://brasilgeo.ai/leadlovers2026/design/react/#testes-msw)

## Guias relacionados

- [TypeScript](https://brasilgeo.ai/leadlovers2026/design/typescript/): Tipagem de props, hooks e formulários em TSX. Instruções: https://brasilgeo.ai/leadlovers2026/design/typescript/agentes.md
- [Tailwind e tokens](https://brasilgeo.ai/leadlovers2026/design/tailwind/): Classes montadas, mapa de variantes e tokens. Instruções: https://brasilgeo.ai/leadlovers2026/design/tailwind/agentes.md
- [Navegação](https://brasilgeo.ai/leadlovers2026/design/navegacao/): Abas, paginação e paleta de comandos. Instruções: https://brasilgeo.ai/leadlovers2026/design/navegacao/agentes.md
- [Dashboards](https://brasilgeo.ai/leadlovers2026/design/dashboards/): Telas de dados com números, tabelas e estados. Instruções: https://brasilgeo.ai/leadlovers2026/design/dashboards/agentes.md
- [frontend-2027](https://brasilgeo.ai/leadlovers2026/design/frontend2027/): Stack moderna e decisões de estado em projeto novo. Instruções: https://brasilgeo.ai/leadlovers2026/design/frontend2027/agentes.md

## Fontes primárias

- [React: versões](https://react.dev/versions)
- [React: You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
- [React: Choosing the State Structure](https://react.dev/learn/choosing-the-state-structure)
