react-patterns

Patrones de React

Patrones idiomáticos de React 18/19 para construir árboles de componentes robustos, accesibles y de alto rendimiento.

Cuándo activarlo

• Escribir o modificar componentes funcionales de React, hooks personalizados o árboles de componentes
• Revisar archivos JSX/TSX
• Diseñar la forma del estado o la composición de componentes
• Migrar componentes de clase o código antiguo con mucho forwardRef/useEffect
• Elegir entre estado local, estado elevado, contexto y almacenes externos
• Trabajar con Server Components / Client Components (Next.js App Router, RSC)
• Implementar formularios con acciones de React 19 o inputs controlados
• Configurar la obtención de datos con TanStack Query / SWR / RSC

Principios fundamentales

1. El renderizado es una función pura de props y estado

// Bien: derivar durante el renderizado
function Cart({ items }: { items: CartItem[] }) {
  const total = items.reduce((sum, i) => sum + i.price * i.qty, 0);
  return <span>{formatMoney(total)}</span>;
}

// Mal: estado derivado almacenado por separado
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>;
}

El estado derivado en useEffect añade un ciclo de renderizado, puede desincronizarse y oscurece el flujo de datos.

2. Efectos secundarios fuera del renderizado

Los efectos, mutaciones, llamadas de red y suscripciones viven en manejadores de eventos o en useEffect, nunca en el cuerpo del renderizado.

3. Composición sobre herencia

React no tiene un modelo de herencia para componentes. Componga con children, render props o props de componentes.

Disciplina de hooks

Consulte rules/react/hooks.md para el conjunto completo de reglas. Aspectos destacados:

• Solo en el nivel superior, nunca condicionales
• Limpiar cada suscripción, intervalo, listener
• Actualizador funcional (setX(prev => prev + 1)) cuando el nuevo estado depende del anterior
• Posición predeterminada: no memorizar — añada useMemo/useCallback solo cuando un perfilador o una cadena de dependencias demuestre que es necesario
• Extraiga un hook personalizado solo cuando la misma secuencia de hooks aparezca en 2 o más componentes

Árbol de decisión de ubicación del estado

¿Usado por un solo componente?
  -> useState dentro de él

¿Usado por el padre + algunos descendientes?
  -> elevarlo al ancestro común más cercano

¿Usado en ramas distantes Y lecturas de baja frecuencia (tema, autenticación, locale)?
  -> React Context

¿Actualizaciones de alta frecuencia compartidas en todo el árbol?
  -> almacén externo (Zustand, Jotai, Redux Toolkit)

¿Derivado de un servidor?
  -> librería de estado del servidor (TanStack Query, SWR, fetch de RSC)

La mayoría de las páginas no necesitan contexto ni un almacén global. Resista la abstracción hasta que la elevación duplicada se vuelva dolorosa.

Server / Client Components (RSC)

// Server Component - predeterminado, asíncrono, nunca envía JavaScript por sí mismo
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 con "use client"
"use client";
export function AddToCartButton({ productId }: { productId: string }) {
  const [pending, startTransition] = useTransition();
  return (
    <button
      disabled={pending}
      onClick={() => startTransition(() => addToCart(productId))}
    >
      {pending ? "Añadiendo..." : "Añadir al carrito"}
    </button>
  );
}

Límites:

• Server -> Client: pase props serializables o children
• Client -> Server: invoque Server Actions mediante <form action={...}> o de forma imperativa desde manejadores de eventos
• Nunca import un Server Component desde un archivo Client Component — compóngalos mediante children

Suspense + Error Boundaries

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

• Coloque los límites de Suspense cerca de los datos, no en la raíz de la ruta — revele el contenido progresivamente
• Error Boundary sigue siendo una API de clase; use react-error-boundary para un envoltorio compatible con hooks
• Un límite captura errores lanzados durante el renderizado, ciclo de vida y constructores de sus hijos — NO en manejadores de eventos o código asíncrono

Formularios

Acciones de formulario de React 19 (preferidas para código nuevo)

"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));
  if (!parsed.success) return { error: "Entrada inválida" };
  await db.user.update({ where: { id: parsed.data.id }, data: parsed.data });
  return { error: null };
}

export function UserForm() {
  const [state, formAction, pending] = useActionState(updateUserAction, initial);
  return (
    <form action={formAction}>
      <input name="name" required />
      <button type="submit" disabled={pending}>Guardar</button>
      {state.error && <p role="alert">{state.error}</p>}
    </form>
  );
}

Inputs controlados

Use controlado cuando el valor impulse otra UI, formatee en cada pulsación de tecla o implemente validación en tiempo real.

Formularios complejos

Para formularios de varios pasos, matrices de campos dinámicas o validación entre campos: use una librería (React Hook Form, TanStack Form). Gestionar el estado por cuenta propia para formularios más allá de la complejidad trivial es una trampa de mantenimiento.

Matriz de decisión de obtención de datos

Necesidad	Herramienta
Datos por solicitud en Next.js App Router	RSC await fetch()
Caché del lado del cliente + mutaciones + invalidación	TanStack Query
Caché ligera del cliente + revalidación	SWR
Suscripciones en tiempo real	Server-Sent Events, WebSockets o la API de suscripción de la librería
Disparar y olvidar una sola vez	fetch() en un manejador de eventos

Evite useEffect + fetch para datos de aplicación — condiciones de carrera, sin caché, sin reintentos, sin integración con Suspense.

Recetas de composición

Slot mediante children

<Layout>
  <Header />
  <Main>{content}</Main>
</Layout>

Slots nombrados

<Page header={<Nav />} sidebar={<Filters />}>
  <Results />
</Page>

Componentes compuestos (estado compartido mediante Context)

<Tabs defaultValue="profile">
  <Tabs.List>
    <Tabs.Trigger value="profile">Perfil</Tabs.Trigger>
    <Tabs.Trigger value="settings">Ajustes</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Panel value="profile"><Profile /></Tabs.Panel>
  <Tabs.Panel value="settings"><Settings /></Tabs.Panel>
</Tabs>

Render prop / función como hijo

Útil cuando el padre necesita pasar parámetros a la salida renderizada:

<DataLoader id={id}>
  {({ data, isLoading }) => isLoading ? <Spinner /> : <UserCard user={data} />}
</DataLoader>

Alternativa moderna: un hook (useData(id)) que devuelve la misma forma — normalmente más limpio.

Rendimiento

Cuándo ayuda realmente React.memo

Envuelva un componente en React.memo solo cuando:

1. Se re-renderice con frecuencia
2. Sus props sean normalmente las mismas entre renderizados
3. Su renderizado sea mediblemente costoso

React.memo añade una comprobación de igualdad en cada renderizado. Si las props difieren en la mayoría de los renderizados, la comprobación es pura sobrecarga.

Evitar cascadas de renderizado

• Eleve el estado hacia abajo en lugar de hacia arriba cuando sea posible
• Divida el contexto: un contexto por preocupación, para que un cambio en themeContext no re-renderice los consumidores de autenticación
• Use useSyncExternalStore para librerías de estado externas — necesario para un renderizado concurrente seguro

Listas

• Proporcione props key estables (id de base de datos, no índice de array)
• Virtualice listas largas con @tanstack/react-virtual o react-window una vez que el recuento de elementos visibles supere ~50 con filas no triviales

Composición accesible primero

• Siempre renderice HTML semántico (<button>, <a>, <nav>, <main>) antes de recurrir a atributos role
• Cada elemento interactivo debe ser accesible mediante teclado
• Los inputs de formulario necesitan etiquetas — <label htmlFor> o aria-label si están etiquetados visualmente por un icono
• Gestione el foco en cambios de ruta y apertura/cierre de modales
• Ejecute axe en pruebas de componentes (consulte skills/react-testing)
• Enlace cruzado: skills/accessibility/SKILL.md cubre criterios WCAG y librerías de patrones

Enrutamiento

Este skill es agnóstico respecto al enrutador. Los patrones anteriores funcionan con React Router, TanStack Router, Next.js App Router, Remix Router. Los patrones específicos del enrutador (loaders, actions, layouts anidados) siguen la documentación del enrutador — son preocupaciones del framework superpuestas al núcleo de React.

Fuera de alcance (Secciones de referencia)

• Especificidades de Next.js: Carga de datos de App Router, Route Handlers, Middleware, Parallel Routes — preocupación separada, use la documentación de Next.js
• React Native: Los patrones específicos de la plataforma difieren lo suficiente como para justificar un skill react-native-patterns separado (aún no presente)
• Remix: Las convenciones de loader/action se superponen con RSC pero siguen la documentación de Remix

Relacionado

• Reglas: rules/react/ — estilo de código, hooks, patrones, seguridad, pruebas
• Skills: react-performance para el conjunto de reglas de rendimiento derivado de Vercel, frontend-patterns para preocupaciones de UI entre frameworks, accessibility, angular-developer para comparación de frameworks
• Agentes: react-reviewer para revisión de código, react-build-resolver para errores de build/bundler
• Comandos: /react-review, /react-build, /react-test

Ejemplos

Hook personalizado para búsqueda con debounce

function useDebounce<T>(value: T, delay = 300): T {
  const [debounced, setDebounced] = useState(value);
  useEffect(() => {
    const id = setTimeout(() => setDebounced(value), delay);
    return () => clearTimeout(id);
  }, [value, delay]);
  return debounced;
}

function SearchBox() {
  const [query, setQuery] = useState("");
  const debounced = useDebounce(query, 300);
  const { data } = useQuery({
    queryKey: ["search", debounced],
    queryFn: () => searchApi(debounced),
    enabled: debounced.length > 0,
  });
  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      <Results items={data ?? []} />
    </>
  );
}

UI optimista con useOptimistic de React 19

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

export function MessageList({ messages }: { messages: Message[] }) {
  const [optimistic, addOptimistic] = useOptimistic(
    messages,
    (state, newMessage: Message) => [...state, newMessage],
  );

  async function send(formData: FormData) {
    const text = String(formData.get("text"));
    addOptimistic({ id: "pending", text, sender: "me" });
    await saveMessage(text);
  }

  return (
    <>
      <ul>{optimistic.map((m) => <li key={m.id}>{m.text}</li>)}</ul>
      <form action={send}>
        <input name="text" />
        <button type="submit">Enviar</button>
      </form>
    </>
  );
}

Dividir contexto para evitar cascadas de renderizado

// Dos contextos: uno cambia raramente, otro con frecuencia
const ThemeContext = createContext<Theme>("light");
const NotificationsContext = createContext<Notification[]>([]);

// Un componente que solo consume ThemeContext NO se re-renderiza cuando cambian las notificaciones