vercel-react-best-practices

Prácticas recomendadas de Vercel para React

Guía completa de optimización de rendimiento para aplicaciones React y Next.js, mantenida por Vercel. Contiene 70 reglas en 8 categorías, priorizadas por impacto para guiar la refactorización y generación de código automatizadas.

Cuándo aplicar

Consulte estas pautas cuando:

• Escriba nuevos componentes React o páginas Next.js
• Implemente fetching de datos (del lado del cliente o del servidor)
• Revise código en busca de problemas de rendimiento
• Refactorice código React/Next.js existente
• Optimice el tamaño del bundle o los tiempos de carga

Categorías de reglas por prioridad

Prioridad	Categoría	Impacto	Prefijo
1	Eliminación de cascadas	CRÍTICO	async-
2	Optimización del tamaño del bundle	CRÍTICO	bundle-
3	Rendimiento del lado del servidor	ALTO	server-
4	Fetching de datos del lado del cliente	MEDIO-ALTO	client-
5	Optimización de re-renderizados	MEDIO	rerender-
6	Rendimiento de renderizado	MEDIO	rendering-
7	Rendimiento de JavaScript	BAJO-MEDIO	js-
8	Patrones avanzados	BAJO	advanced-

Referencia rápida

1. Eliminación de cascadas (CRÍTICO)

• async-cheap-condition-before-await - Verificar condiciones síncronas baratas antes de esperar flags o valores remotos
• async-defer-await - Mover await a las ramas donde realmente se usa
• async-parallel - Usar Promise.all() para operaciones independientes
• async-dependencies - Usar better-all para dependencias parciales
• async-api-routes - Iniciar promesas temprano, esperar tarde en rutas API
• async-suspense-boundaries - Usar Suspense para transmitir contenido

2. Optimización del tamaño del bundle (CRÍTICO)

• bundle-barrel-imports - Importar directamente, evitar archivos barrel
• bundle-analyzable-paths - Preferir rutas de importación y sistema de archivos analizables estáticamente para evitar bundles y trazas amplias
• bundle-dynamic-imports - Usar next/dynamic para componentes pesados
• bundle-defer-third-party - Cargar análisis/registro después de la hidratación
• bundle-conditional - Cargar módulos solo cuando la característica está activada
• bundle-preload - Precargar al pasar el ratón/enfocar para velocidad percibida

3. Rendimiento del lado del servidor (ALTO)

• server-auth-actions - Autenticar acciones del servidor como rutas API
• server-cache-react - Usar React.cache() para deduplicación por solicitud
• server-cache-lru - Usar caché LRU para almacenamiento en caché entre solicitudes
• server-dedup-props - Evitar serialización duplicada en props de RSC
• server-hoist-static-io - Elevar E/S estática (fuentes, logotipos) al nivel del módulo
• server-no-shared-module-state - Evitar estado mutable a nivel de módulo en RSC/SSR
• server-serialization - Minimizar datos pasados a componentes del cliente
• server-parallel-fetching - Reestructurar componentes para paralelizar fetch
• server-parallel-nested-fetching - Encadenar fetch anidados por elemento en Promise.all
• server-after-nonblocking - Usar after() para operaciones no bloqueantes

4. Fetching de datos del lado del cliente (MEDIO-ALTO)

• client-swr-dedup - Usar SWR para deduplicación automática de solicitudes
• client-event-listeners - Desduplicar listeners de eventos globales
• client-passive-event-listeners - Usar listeners pasivos para scroll
• client-localstorage-schema - Versionar y minimizar datos de localStorage

5. Optimización de re-renderizados (MEDIO)

• rerender-defer-reads - No suscribirse a estado solo usado en callbacks
• rerender-memo - Extraer trabajo costoso en componentes memorizados
• rerender-memo-with-default-value - Elevar props no primitivos predeterminados
• rerender-dependencies - Usar dependencias primitivas en efectos
• rerender-derived-state - Suscribirse a booleanos derivados, no a valores crudos
• rerender-derived-state-no-effect - Derivar estado durante el renderizado, no en efectos
• rerender-functional-setstate - Usar setState funcional para callbacks estables
• rerender-lazy-state-init - Pasar función a useState para valores costosos
• rerender-simple-expression-in-memo - Evitar memo para primitivos simples
• rerender-split-combined-hooks - Dividir hooks con dependencias independientes
• rerender-move-effect-to-event - Poner lógica de interacción en manejadores de eventos
• rerender-transitions - Usar startTransition para actualizaciones no urgentes
• rerender-use-deferred-value - Diferir renderizados costosos para mantener la entrada receptiva
• rerender-use-ref-transient-values - Usar refs para valores transitorios frecuentes
• rerender-no-inline-components - No definir componentes dentro de componentes

6. Rendimiento de renderizado (MEDIO)

• rendering-animate-svg-wrapper - Animar envoltorio div, no elemento SVG
• rendering-content-visibility - Usar content-visibility para listas largas
• rendering-hoist-jsx - Extraer JSX estático fuera de componentes
• rendering-svg-precision - Reducir precisión de coordenadas SVG
• rendering-hydration-no-flicker - Usar script en línea para datos solo del cliente
• rendering-hydration-suppress-warning - Suprimir discrepancias esperadas
• rendering-activity - Usar componente Activity para mostrar/ocultar
• rendering-conditional-render - Usar ternario, no && para condicionales
• rendering-usetransition-loading - Preferir useTransition para estado de carga
• rendering-resource-hints - Usar sugerencias de recursos de React DOM para precarga
• rendering-script-defer-async - Usar defer o async en etiquetas script

7. Rendimiento de JavaScript (BAJO-MEDIO)

• js-batch-dom-css - Agrupar cambios CSS mediante clases o cssText
• js-index-maps - Construir Map para búsquedas repetidas
• js-cache-property-access - Almacenar en caché propiedades de objetos en bucles
• js-cache-function-results - Almacenar en caché resultados de funciones en Map a nivel de módulo
• js-cache-storage - Almacenar en caché lecturas de localStorage/sessionStorage
• js-combine-iterations - Combinar múltiples filter/map en un solo bucle
• js-length-check-first - Verificar longitud de array antes de comparación costosa
• js-early-exit - Retornar temprano de funciones
• js-hoist-regexp - Elevar creación de RegExp fuera de bucles
• js-min-max-loop - Usar bucle para min/max en lugar de sort
• js-set-map-lookups - Usar Set/Map para búsquedas O(1)
• js-tosorted-immutable - Usar toSorted() para inmutabilidad
• js-flatmap-filter - Usar flatMap para mapear y filtrar en un solo paso
• js-request-idle-callback - Diferir trabajo no crítico al tiempo de inactividad del navegador

8. Patrones avanzados (BAJO)

• advanced-effect-event-deps - No poner resultados de useEffectEvent en dependencias de efecto
• advanced-event-handler-refs - Almacenar manejadores de eventos en refs
• advanced-init-once - Inicializar la aplicación una vez por carga
• advanced-use-latest - useLatest para refs de callback estables

Cómo usar

Lea los archivos de reglas individuales para explicaciones detalladas y ejemplos de código:

rules/async-parallel.md
rules/bundle-barrel-imports.md

Cada archivo de regla contiene:

• Breve explicación de por qué es importante
• Ejemplo de código incorrecto con explicación
• Ejemplo de código correcto con explicación
• Contexto adicional y referencias

Documento completo compilado

Para la guía completa con todas las reglas expandidas: AGENTS.md