Padrões do React

Padrões idiomáticos do React 18/19 para construir árvores de componentes robustas, acessíveis e de alto desempenho.

Quando Ativar

• Escrevendo ou modificando componentes de função React, hooks personalizados ou árvores de componentes
• Revisando arquivos JSX/TSX
• Projetando a forma do estado ou a composição de componentes
• Migrando componentes de classe ou código mais antigo com uso intensivo de forwardRef/useEffect
• Escolhendo entre estado local, estado elevado, contexto e stores externos
• Trabalhando com Componentes de Servidor / Componentes de Cliente (Next.js App Router, RSC)
• Implementando formulários com ações do React 19 ou inputs controlados
• Conectando a busca de dados com TanStack Query / SWR / RSC

Princípios Fundamentais

1. Renderizar é uma Função Pura de Props e Estado

// Good: derive during render
function Cart({ items }: { items: CartItem[] }) {
  const total = items.reduce((sum, i) => sum + i.price * i.qty, 0);
  return <span>{formatMoney(total)}</span>;
}

// Bad: derived state stored separately
function Cart({ items }: { items: CartItem[] }) {
  const [total, setTotal] = useState(0);
  useEffect(() => {
    setTotal(items.reduce((sum, i) => sum + i.price * i.qty, 0));
  }, [items]);
  return <span>{formatMoney(total)}</span>;
}

O estado derivado em useEffect adiciona um ciclo de renderização, pode dessincronizar e obscurece o fluxo de dados.

2. Efeitos Colaterais Fora do Render

Efeitos, mutações, chamadas de rede e assinaturas vivem em manipuladores de eventos ou useEffect — nunca no corpo do render.

3. Composição Acima de Herança

O React não tem um modelo de herança para componentes. Componha com children, render props ou props de componentes.

Disciplina de Hooks

Veja rules/react/hooks.md para o conjunto completo de regras. Destaques:

• Apenas no nível superior, nunca condicional
• Limpe toda assinatura, intervalo, listener
• Atualizador funcional (setX(prev => prev + 1)) quando o novo estado depende do antigo
• Posição padrão: não memoize — adicione useMemo/useCallback apenas quando um profiler ou uma cadeia de dependências provar que importa
• Extraia um hook personalizado apenas quando a mesma sequência de hooks aparece em 2+ componentes

Árvore de Decisão de Localização de Estado

Used by one component?
  -> useState inside it

Used by parent + a few descendants?
  -> lift to nearest common ancestor

Used across distant branches AND low-frequency reads (theme, auth, locale)?
  -> React Context

High-frequency updates shared across the tree?
  -> external store (Zustand, Jotai, Redux Toolkit)

Derived from a server?
  -> server-state library (TanStack Query, SWR, RSC fetch)

A maioria das páginas não precisa de contexto ou de um store global. Resista à abstração até que o levantamento duplicado se torne doloroso.

Componentes de Servidor / Cliente (RSC)

// Server Component - default, async, never ships JS for itself
export default async function ProductPage({ params }: { params: { id: string } }) {
  const product = await db.product.findUnique({ where: { id: params.id } });
  if (!product) notFound();
  return <ProductView product={product} />;
}

// Client Component - opt in with "use client"
"use client";
export function AddToCartButton({ productId }: { productId: string }) {
  const [pending, startTransition] = useTransition();
  return (
    <button
      disabled={pending}
      onClick={() => startTransition(() => addToCart(productId))}
    >
      {pending ? "Adding..." : "Add to cart"}
    </button>
  );
}

Limites:

• Servidor -> Cliente: passe props serializáveis ou children
• Cliente -> Servidor: invoque Server Actions via <form action={...}> ou imperativamente a partir de manipuladores de eventos
• Nunca import um Componente de Servidor de um arquivo de Componente de Cliente — componha-os via children em vez disso

Suspense + Error Boundaries

<ErrorBoundary fallback={<ErrorView />}>
  <Suspense fallback={<UserSkeleton />}>
    <UserDetail id={id} />
  </Suspense>
</ErrorBoundary>

• Coloque limites do Suspense perto dos dados, não na raiz da rota — revele o conteúdo progressivamente
• Error Boundary continua sendo uma API de classe; use react-error-boundary para um wrapper amigável a hooks
• Um limite captura erros lançados durante a renderização, ciclo de vida e construtores de seus filhos — NÃO em manipuladores de eventos ou código assíncrono

Formulários

Ações de formulário do React 19 (preferencial para código novo)

"use client";
import { useActionState } from "react";

const initial = { error: null as string | null };

async function updateUserAction(_prev: typeof initial, formData: FormData) {
  "use server";
  const parsed = UserSchema.safeParse(Object.fromEntries(formData));

…