theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/rendimiento-react/SKILL.md

@@ -0,0 +1,567 @@
+---
+name: rendimiento-react
+description: Patrones de optimización de rendimiento para React y Next.js. Organiza más de 70 reglas en 8 categorías por prioridad — waterfalls, tamaño de bundle, lado servidor, fetching en cliente, re-renders, renderizado, micro-rendimiento de JS y patrones avanzados. Úsala al escribir, revisar o refactorizar código React/Next.js con foco en rendimiento.
+---
+
+# Rendimiento en React
+
+Patrones de optimización de rendimiento para React 18/19 y Next.js. Esta skill organiza las reglas por prioridad y ofrece guía en forma de árbol de decisión para revisiones de código y refactorizaciones activas.
+
+## Cuándo activarla
+
+- Al escribir o revisar código React/Next.js con foco en rendimiento
+- Al diagnosticar cargas de página lentas, interacciones lentas o CPU alta en el cliente
+- Al auditar el tamaño del bundle o regresiones en las Core Web Vitals de Lighthouse
+- Al eliminar waterfalls en Server Components / rutas de API
+- Al reducir re-renders del lado del cliente
+- Al optimizar listas largas, animaciones o la hidratación
+- Al auditar decisiones de optimización en PRs que tocan `app/`, `pages/`, `components/` o capas de datos
+
+## Índice de prioridades
+
+| Prioridad | Categoría | Prefijo | Cuándo importa |
+|---|---|---|---|
+| 1 — CRÍTICA | Eliminación de waterfalls | `async-` | Siempre que un `await` va seguido de otro `await` independiente |
+| 2 — CRÍTICA | Optimización del tamaño de bundle | `bundle-` | JS de primera carga, imports por ruta, librerías de terceros |
+| 3 — ALTA | Rendimiento del lado servidor | `server-` | RSC, Server Actions, rutas de API, SSR |
+| 4 — MEDIA-ALTA | Fetching de datos en el cliente | `client-` | SWR / TanStack Query / `fetch` crudo en hooks |
+| 5 — MEDIA | Optimización de re-renders | `rerender-` | Actualizaciones de estado de alta frecuencia, propagación padre-hijo |
+| 6 — MEDIA | Rendimiento de renderizado | `rendering-` | Listas largas, animaciones, hidratación |
+| 7 — BAJA-MEDIA | Rendimiento de JavaScript | `js-` | Bucles calientes, asignaciones frecuentes |
+| 8 — BAJA | Patrones avanzados | `advanced-` | Integración de effect events, refs estables |
+
+## 1. Eliminación de waterfalls (CRÍTICA)
+
+> "Los waterfalls son el asesino de rendimiento #1" — cada `await` secuencial suma la latencia completa de la red.
+
+### Condiciones baratas antes del await
+
+Verifica condiciones síncronas (props, env, flags fijos) antes de esperar datos remotos.
+
+```ts
+// INCORRECTO
+async function Page({ id }: { id: string }) {
+  const flag = await getFlag("show-page");
+  if (!flag || !id) return null;
+  const data = await getData(id);
+  // ...
+}
+
+// CORRECTO — corta primero por la condición síncrona barata
+async function Page({ id }: { id: string }) {
+  if (!id) return null;
+  const flag = await getFlag("show-page");
+  if (!flag) return null;
+  const data = await getData(id);
+}
+```
+
+### Difiere los awaits hasta que se usen
+
+Mueve el `await` a la rama que usa el dato.
+
+```ts
+// INCORRECTO — espera antes de decidir si necesita el dato
+const user = await getUser(id);
+if (mode === "guest") return renderGuest();
+return renderUser(user);
+
+// CORRECTO
+if (mode === "guest") return renderGuest();
+const user = await getUser(id);
+return renderUser(user);
+```
+
+### Promise.all para trabajo independiente
+
+```ts
+// INCORRECTO — secuencial
+const user = await getUser(id);
+const posts = await getPosts(id);
+const followers = await getFollowers(id);
+
+// CORRECTO — en paralelo
+const [user, posts, followers] = await Promise.all([
+  getUser(id),
+  getPosts(id),
+  getFollowers(id),
+]);
+```
+
+### Dependencias parciales — arranca pronto, espera tarde
+
+```ts
+// CORRECTO — lanza todas las promesas y espera solo cuando cada resultado hace falta
+const userP = getUser(id);
+const postsP = getPosts(id);
+const profile = await getProfile(id);
+if (profile.private) return null;
+const [user, posts] = await Promise.all([userP, postsP]);
+```
+
+### Suspense para streaming
+
+Acerca los límites de `<Suspense>` a los datos para que la página pinte lo que pueda mientras los subárboles más lentos llegan por streaming. El costo: desplazamiento de layout cuando llega el contenido — reserva espacio (skeleton o `min-height`).
+
+### Server Components: paralelismo por composición
+
+```tsx
+// INCORRECTO — los awaits hermanos corren en secuencia dentro de un mismo componente
+export default async function Page() {
+  const user = await getUser();
+  const cart = await getCart();
+  return <View user={user} cart={cart} />;
+}
+
+// CORRECTO — divide en hijos; React los ejecuta en paralelo
+export default async function Page() {
+  return (
+    <View>
+      <UserSection />
+      <CartSection />
+    </View>
+  );
+}
+```
+
+## 2. Optimización del tamaño de bundle (CRÍTICA)
+
+### Imports directos, no barrels
+
+Los archivos barrel `index.ts` obligan al bundler a recorrer el grafo completo de módulos aunque el tree-shaking elimine la mayor parte. Los imports directos ahorran 200-800 ms de JS de primera carga en muchas apps reales.
+
+```ts
+// INCORRECTO
+import { Button, Card, Modal } from "@/components";
+
+// CORRECTO
+import { Button } from "@/components/Button";
+import { Card } from "@/components/Card";
+import { Modal } from "@/components/Modal";
+```
+
+Next.js 13.5+ incluye [Optimize Package Imports](https://nextjs.org/docs/app/api-reference/next-config-js/optimizePackageImports), que automatiza esto para los paquetes listados — úsalo; los imports directos manuales siguen siendo necesarios para las librerías no listadas.
+
+### Rutas analizables estáticamente
+
+```ts
+// INCORRECTO — anula el análisis del bundler y del trazado
+const mod = await import(`./pages/${name}`);
+
+// CORRECTO — explícito por rama
+const mod = name === "home" ? await import("./pages/home") : await import("./pages/about");
+```
+
+### Imports dinámicos para componentes pesados
+
+```tsx
+import dynamic from "next/dynamic";
+
+const HeavyChart = dynamic(() => import("./HeavyChart"), {
+  loading: () => <Skeleton />,
+  ssr: false, // cuando es solo-cliente
+});
+```
+
+### Difiere los scripts de terceros
+
+Carga analítica, logging y widgets de soporte DESPUÉS de la hidratación. Usa `next/script` con `strategy="afterInteractive"` (por defecto) o `"lazyOnload"`.
+
+### Carga condicional de módulos
+
+```tsx
+if (user.role === "admin") {
+  const { AdminPanel } = await import("./admin/AdminPanel");
+  // ...
+}
+```
+
+### Precarga en hover/focus
+
+Dispara `<link rel="preload">` o `import()` en hover para que el bundle ya esté en caché cuando el usuario haga clic.
+
+## 3. Rendimiento del lado servidor (ALTA)
+
+### Autentica las Server Actions como si fueran rutas de API
+
+Toda función `"use server"` es un endpoint público. Autentica Y autoriza dentro de la acción — nunca confíes en el control de acceso del Client Component que la invoca.
+
+```ts
+"use server";
+export async function deleteUser(formData: FormData) {
+  const session = await getSession();
+  if (!session?.user) throw new Error("No autorizado");
+  const targetId = String(formData.get("id"));
+  if (session.user.role !== "admin" && session.user.id !== targetId) {
+    throw new Error("Prohibido");
+  }
+  await db.user.delete({ where: { id: targetId } });
+}
+```
+
+### `React.cache()` para deduplicación por request
+
+```ts
+import { cache } from "react";
+
+export const getUser = cache(async (id: string) => {
+  return db.user.findUnique({ where: { id } });
+});
+```
+
+`React.cache` deduplica dentro de un mismo request. Llamar a `getUser("1")` desde tres Server Components en el mismo render = una sola consulta a la BD.
+
+### Caché LRU para datos entre requests
+
+Para datos que NO cambian por request (configuración, tablas de consulta), cachea fuera de React con una caché LRU o `unstable_cache`.
+
+### Evita la serialización duplicada en props de RSC
+
+Cuando un Server Component renderiza los mismos datos en varios Client Components, los datos se serializan una vez por consumidor. Sube el Client Component en el árbol y pasa children.
+
+### Eleva la E/S estática al ámbito de módulo
+
+```ts
+// CORRECTO — se ejecuta una vez al cargar el módulo
+const fontData = readFileSync(fontPath);
+
+export async function Page() {
+  return <Banner font={fontData} />;
+}
+```
+
+### Nada de estado mutable a nivel de módulo en RSC/SSR
+
+El estado de módulo en el servidor se comparte entre todos los requests — una condición de carrera entre usuarios. Usa almacenamiento con ámbito de request (`headers()`, `cookies()`, contexto asíncrono).
+
+### Minimiza los datos pasados a Client Components
+
+Serializa solo lo que el cliente necesita. Elimina campos, pagina y proyecta columnas en la capa de BD.
+
+### Paraleliza fetches anidados con Promise.all por elemento
+
+```ts
+const users = await getUsers();
+const enriched = await Promise.all(
+  users.map(async (u) => ({ ...u, posts: await getPostsFor(u.id) })),
+);
+```
+
+### Usa `after()` para trabajo no bloqueante
+
+El `after()` de Next.js 15 ejecuta trabajo después de enviar la respuesta — logging, calentamiento de caché, analítica.
+
+```ts
+import { after } from "next/server";
+export async function GET() {
+  const data = await getData();
+  after(() => logAnalytics(data));
+  return Response.json(data);
+}
+```
+
+## 4. Fetching de datos en el cliente (MEDIA-ALTA)
+
+### SWR / TanStack Query para deduplicación
+
+Varios componentes que llaman a `useUser(id)` deben compartir una sola petición de red y una sola entrada de caché. Usa SWR o TanStack Query — nunca improvises tu propio `useEffect` + `fetch` para datos compartidos.
+
+### Deduplica los listeners de eventos globales
+
+```tsx
+// INCORRECTO — cada componente añade el suyo
+useEffect(() => {
+  window.addEventListener("scroll", handler);
+  return () => window.removeEventListener("scroll", handler);
+}, []);
+
+// CORRECTO — un único listener compartido vía un hook + sujeto global
+const useScroll = createScrollHook(); // sujeto singleton por debajo
+```
+
+### Listeners pasivos para scroll
+
+```ts
+window.addEventListener("scroll", handler, { passive: true });
+```
+
+Mejora la fluidez del scroll; el listener no puede llamar a `preventDefault()`.
+
+### localStorage: versiona y minimiza
+
+- Guarda siempre un campo `version`; increméntalo al cambiar el esquema y migra o descarta los datos antiguos
+- Mantén los payloads pequeños — `localStorage` es síncrono y bloquea el hilo principal
+
+## 5. Optimización de re-renders (MEDIA)
+
+### No te suscribas a estado usado solo en callbacks
+
+```tsx
+// INCORRECTO — re-renderiza cada vez que cambia count
+const count = useStore((s) => s.count);
+const handler = () => doSomething(count);
+
+// CORRECTO — léelo una vez al invocar
+const handler = () => {
+  const count = useStore.getState().count;
+  doSomething(count);
+};
+```
+
+### Extrae el trabajo caro a componentes memoizados
+
+```tsx
+// CORRECTO — el hijo solo re-renderiza cuando cambia `items`
+const Heavy = memo(function Heavy({ items }: { items: Item[] }) {
+  return <Chart data={transform(items)} />;
+});
+```
+
+### Eleva las props por defecto no primitivas
+
+```tsx
+// INCORRECTO — un array nuevo en cada render rompe memo
+<List items={items ?? []} />
+
+// CORRECTO
+const EMPTY: Item[] = [];
+<List items={items ?? EMPTY} />
+```
+
+### Dependencias primitivas en efectos
+
+```tsx
+// INCORRECTO — identidad de objeto nueva en cada render
+useEffect(() => {}, [{ id, name }]);
+
+// CORRECTO — primitivas
+useEffect(() => {}, [id, name]);
+```
+
+### Suscríbete a booleanos derivados, no a valores crudos
+
+```tsx
+// INCORRECTO — re-renderiza ante cualquier cambio del carrito
+const cart = useStore((s) => s.cart);
+const hasItems = cart.length > 0;
+
+// CORRECTO — re-renderiza solo cuando cambia el estado de vacío
+const hasItems = useStore((s) => s.cart.length > 0);
+```
+
+### Deriva durante el render, nunca vía `useEffect`
+
+```tsx
+// INCORRECTO
+const [full, setFull] = useState("");
+useEffect(() => setFull(`${first} ${last}`), [first, last]);
+
+// CORRECTO
+const full = `${first} ${last}`;
+```
+
+### `setState` funcional para callbacks estables
+
+```tsx
+// CORRECTO
+const increment = useCallback(() => setCount((c) => c + 1), []);
+```
+
+### Inicializador perezoso de estado para valores caros
+
+```tsx
+const [tree] = useState(() => parseTree(largeInput));
+```
+
+### Evita memo para primitivas simples
+
+`useMemo(() => x + 1, [x])` es sobrecosto. Memo compensa cuando hay identidad de objeto o cómputo caro.
+
+### Divide los hooks con dependencias independientes
+
+```tsx
+// INCORRECTO — ambos selectores se recalculan si cambia cualquiera de las fuentes
+const { a, b } = useSomething(source1, source2);
+
+// CORRECTO
+const a = useA(source1);
+const b = useB(source2);
+```
+
+### Mueve la lógica de interacción a los manejadores de eventos
+
+Los manejadores de eventos corren solo con la acción del usuario — `useEffect` se re-ejecuta cada vez que cambian sus dependencias.
+
+### `startTransition` para actualizaciones no urgentes
+
+```tsx
+const [pending, startTransition] = useTransition();
+startTransition(() => setFilters(newFilters));
+```
+
+### `useDeferredValue` para renders caros
+
+```tsx
+const deferredQuery = useDeferredValue(query);
+const results = useMemo(() => expensiveSearch(deferredQuery), [deferredQuery]);
+```
+
+### `useRef` para valores transitorios frecuentes
+
+Para valores que cambian a menudo pero no deben disparar re-render (marcas de tiempo, última tecla, acumuladores).
+
+### No definas componentes dentro de componentes
+
+```tsx
+// INCORRECTO — Inner es un componente nuevo en cada render de Outer
+function Outer() {
+  const Inner = () => <span />;
+  return <Inner />;
+}
+```
+
+Cada render crea un tipo `Inner` nuevo, lo que anula la reconciliación y desmonta a los hijos.
+
+## 6. Rendimiento de renderizado (MEDIA)
+
+### Anima el contenedor, no el SVG
+
+Transformar un `<div>` contenedor alrededor de un SVG se acelera por GPU; transformar el propio SVG dispara paint.
+
+### `content-visibility: auto` para listas largas
+
+```css
+.row { content-visibility: auto; contain-intrinsic-size: auto 80px; }
+```
+
+El navegador omite el renderizado fuera de pantalla — una gran mejora en listas con cientos de filas.
+
+### Eleva el JSX estático
+
+```tsx
+const STATIC_HEADER = <h1>Título</h1>;
+function Page() {
+  return <>{STATIC_HEADER}<Body /></>;
+}
+```
+
+### SVG: reduce la precisión de coordenadas
+
+`d="M10.123456,20.654321"` → `d="M10.12,20.65"`. Cada dígito cuesta bytes; la diferencia visual es sub-píxel.
+
+### Hidratación sin parpadeo vía script inline
+
+Para valores necesarios antes de la hidratación (tema, locale), incrusta un `<script>` que fije `document.documentElement.dataset.*` antes de que React monte.
+
+### Suprime los desajustes de hidratación esperados de forma acotada
+
+```tsx
+<time suppressHydrationWarning>{new Date().toLocaleString()}</time>
+```
+
+Úsalo SOLO en nodos hoja con divergencia conocida — nunca en un árbol que contenga otros hijos.
+
+### `<Activity>` para mostrar/ocultar en lugar de montar/desmontar
+
+El `<Activity mode="visible|hidden">` de React 19 mantiene el estado del árbol y los efectos montados pero ocultos — más barato que desmontar/remontar para pestañas y acordeones.
+
+### Ternario en lugar de `&&` para render condicional
+
+```tsx
+// INCORRECTO — `0` se renderiza como nodo de texto
+{count && <Badge>{count}</Badge>}
+
+// CORRECTO
+{count > 0 ? <Badge>{count}</Badge> : null}
+```
+
+### `useTransition` para estados de carga
+
+Empareja `startTransition` con la acción; React muestra la UI anterior como `isPending` mientras se calcula el siguiente estado.
+
+### Resource hints de React DOM
+
+```tsx
+import { preload, preconnect } from "react-dom";
+preload("/api/critical", { as: "fetch" });
+preconnect("https://api.example.com");
+```
+
+### `defer` / `async` en etiquetas `<script>`
+
+`defer` para ejecución ordenada tras DOMContentLoaded; `async` para dispara-y-olvida.
+
+## 7. Rendimiento de JavaScript (BAJA-MEDIA)
+
+- **Agrupa los cambios de DOM/CSS** — aplícalos con un cambio de clase o `cssText`, no propiedad por propiedad
+- **`Map` para búsquedas repetidas** — `O(1)` frente al recorrido lineal `O(n)`
+- **Cachea el acceso a propiedades en bucles** — `const len = arr.length`
+- **Memoiza funciones puras** — `Map<clave, resultado>` a nivel de módulo
+- **Cachea las lecturas de `localStorage`** — API síncrona; una lectura por render
+- **Combina `filter().map()` en una sola pasada** — `flatMap` o un único `for`
+- **Comprueba primero la longitud del array** antes de comparaciones caras
+- **Retorno temprano** en las funciones
+- **Eleva las RegExp** fuera de los bucles — la compilación no es gratis
+- **Bucle para mín/máx** en lugar de `sort()` — `O(n)` frente a `O(n log n)`
+- **`Set`/`Map` para pertenencia** — `O(1)` frente a `Array.includes` `O(n)`
+- **`toSorted()` en lugar de mutación** cuando la inmutabilidad importa
+- **`flatMap` para mapear y filtrar en una sola pasada**
+- **`requestIdleCallback`** para trabajo no crítico
+
+## 8. Patrones avanzados (BAJA)
+
+### Dependencias de `useEffectEvent`
+
+Los valores de `useEffectEvent` son estables — NO los añadas a las dependencias del efecto.
+
+### Refs de manejadores de eventos
+
+Para callbacks estables pasados a hijos memoizados:
+
+```tsx
+const handlerRef = useRef(handler);
+useEffect(() => { handlerRef.current = handler; });
+const stable = useCallback((arg) => handlerRef.current(arg), []);
+```
+
+### Inicializa una sola vez por carga de la app
+
+Para singletons a nivel de módulo (telemetría, logger), protégelos con un flag en el ámbito del módulo — no con `useEffect`.
+
+### `useLatest` para refs de callbacks estables
+
+```tsx
+function useLatest<T>(value: T) {
+  const ref = useRef(value);
+  ref.current = value;
+  return ref;
+}
+```
+
+## Herramientas automatizadas
+
+Muchas de estas reglas ya están automatizadas:
+
+- **Optimize Package Imports de Next.js 13.5+** — optimización de imports barrel
+- **React Compiler** (RFC, en canary) — memoización automática
+- **Turbopack** — builds más rápidos, mejor tree-shaking
+- **Bundle Analyzer** (`@next/bundle-analyzer`) — visualiza el JS de primera carga
+
+Cuando el proyecto adopte React Compiler, degrada las reglas manuales de memoización `rerender-*` a "solo revisión" — el compilador las cubre. Los `useMemo`/`useCallback` manuales se convierten en ruido innecesario.
+
+## Correspondencia con Lighthouse / Web Vitals
+
+| Métrica | Categorías más relevantes |
+|---|---|
+| **LCP** (Largest Contentful Paint) | Waterfalls, Tamaño de bundle, Resource hints |
+| **INP** (Interaction to Next Paint) | Re-renders, Renderizado, JavaScript |
+| **CLS** (Cumulative Layout Shift) | Renderizado (ubicación de Suspense, dimensiones de imágenes) |
+| **TBT** (Total Blocking Time) | Tamaño de bundle, JavaScript, Diferir terceros |
+| **FID** (legado) | Tamaño de bundle, Hidratación |
+
+## Relacionado
+
+- Skills: [patrones-react](../patrones-react/SKILL.md), [testing-react](../testing-react/SKILL.md), [patrones-frontend](../patrones-frontend/SKILL.md), [accesibilidad](../accesibilidad/SKILL.md), [patrones-nextjs](../patrones-nextjs/SKILL.md)
+- Reglas: [rules/react/](../../rules/react/)
+- Agentes: `revisor-react` aplica estas reglas en la revisión de código; `resolutor-builds-react` atiende los fallos de build relacionados
+- Comandos: `/revisar-react`, `/build-react`, `/test-react`