vercel-react-best-practices

Vercel React Best Practices

Guide complet d'optimisation des performances pour les applications React et Next.js, maintenu par Vercel. Contient 70 règles réparties en 8 catégories, classées par ordre de priorité d'impact pour guider le refactoring automatisé et la génération de code.

Quand l'utiliser

Consultez ces directives lorsque :

• Vous écrivez de nouveaux composants React ou des pages Next.js
• Vous implémentez du data fetching (côté client ou serveur)
• Vous révisez du code pour des problèmes de performance
• Vous refactorez du code React/Next.js existant
• Vous optimisez la taille du bundle ou les temps de chargement

Catégories de règles par priorité

Priorité	Catégorie	Impact	Préfixe
1	Élimination des cascades	CRITIQUE	async-
2	Optimisation de la taille du bundle	CRITIQUE	bundle-
3	Performance côté serveur	ÉLEVÉ	server-
4	Data fetching côté client	MOYEN-ÉLEVÉ	client-
5	Optimisation des re-rendus	MOYEN	rerender-
6	Performance de rendu	MOYEN	rendering-
7	Performance JavaScript	FAIBLE-MOYEN	js-
8	Schémas avancés	FAIBLE	advanced-

Référence rapide

1. Élimination des cascades (CRITIQUE)

• async-cheap-condition-before-await - Vérifier les conditions synchrones peu coûteuses avant d'attendre les flags ou valeurs distantes
• async-defer-await - Déplacer await dans les branches où il est réellement utilisé
• async-parallel - Utiliser Promise.all() pour les opérations indépendantes
• async-dependencies - Utiliser better-all pour les dépendances partielles
• async-api-routes - Démarrer les promesses tôt, attendre tard dans les routes API
• async-suspense-boundaries - Utiliser Suspense pour diffuser le contenu

2. Optimisation de la taille du bundle (CRITIQUE)

• bundle-barrel-imports - Importer directement, éviter les fichiers barrel
• bundle-analyzable-paths - Privilégier les chemins d'import et de système de fichiers statiquement analysables pour éviter des bundles et traces trop larges
• bundle-dynamic-imports - Utiliser next/dynamic pour les composants lourds
• bundle-defer-third-party - Charger les outils d'analyse et de journalisation après l'hydratation
• bundle-conditional - Charger les modules uniquement lorsque la fonctionnalité est activée
• bundle-preload - Précharger au survol/au focus pour une rapidité perçue

3. Performance côté serveur (ÉLEVÉ)

• server-auth-actions - Authentifier les actions serveur comme les routes API
• server-cache-react - Utiliser React.cache() pour la déduplication par requête
• server-cache-lru - Utiliser un cache LRU pour la mise en cache entre requêtes
• server-dedup-props - Éviter la sérialisation en double dans les props RSC
• server-hoist-static-io - Déplacer les E/S statiques (polices, logos) au niveau du module
• server-no-shared-module-state - Éviter l'état mutable partagé au niveau du module dans RSC/SSR
• server-serialization - Minimiser les données transmises aux composants clients
• server-parallel-fetching - Restructurer les composants pour paralléliser les requêtes
• server-parallel-nested-fetching - Enchaîner les requêtes imbriquées par élément dans Promise.all
• server-after-nonblocking - Utiliser after() pour les opérations non bloquantes

4. Data fetching côté client (MOYEN-ÉLEVÉ)

• client-swr-dedup - Utiliser SWR pour la déduplication automatique des requêtes
• client-event-listeners - Dédupliquer les écouteurs d'événements globaux
• client-passive-event-listeners - Utiliser des écouteurs passifs pour le défilement
• client-localstorage-schema - Versionner et minimiser les données localStorage

5. Optimisation des re-rendus (MOYEN)

• rerender-defer-reads - Ne pas s'abonner à un état uniquement utilisé dans les callbacks
• rerender-memo - Extraire le travail coûteux dans des composants mémorisés
• rerender-memo-with-default-value - Déplacer les props non primitives par défaut
• rerender-dependencies - Utiliser des dépendances primitives dans les effets
• rerender-derived-state - S'abonner à des booléens dérivés, pas aux valeurs brutes
• rerender-derived-state-no-effect - Dériver l'état pendant le rendu, pas dans les effets
• rerender-functional-setstate - Utiliser setState fonctionnel pour des callbacks stables
• rerender-lazy-state-init - Passer une fonction à useState pour les valeurs coûteuses
• rerender-simple-expression-in-memo - Éviter memo pour les primitives simples
• rerender-split-combined-hooks - Diviser les hooks avec des dépendances indépendantes
• rerender-move-effect-to-event - Mettre la logique d'interaction dans les gestionnaires d'événements
• rerender-transitions - Utiliser startTransition pour les mises à jour non urgentes
• rerender-use-deferred-value - Différer les rendus coûteux pour garder la saisie réactive
• rerender-use-ref-transient-values - Utiliser des refs pour les valeurs transitoires fréquentes
• rerender-no-inline-components - Ne pas définir de composants à l'intérieur d'autres composants

6. Performance de rendu (MOYEN)

• rendering-animate-svg-wrapper - Animer le wrapper div, pas l'élément SVG
• rendering-content-visibility - Utiliser content-visibility pour les longues listes
• rendering-hoist-jsx - Extraire le JSX statique en dehors des composants
• rendering-svg-precision - Réduire la précision des coordonnées SVG
• rendering-hydration-no-flicker - Utiliser un script inline pour les données côté client uniquement
• rendering-hydration-suppress-warning - Supprimer les avertissements de divergence attendus
• rendering-activity - Utiliser le composant Activity pour afficher/masquer
• rendering-conditional-render - Utiliser l'opérateur ternaire, pas && pour les conditionnels
• rendering-usetransition-loading - Privilégier useTransition pour l'état de chargement
• rendering-resource-hints - Utiliser les indices de ressources React DOM pour le préchargement
• rendering-script-defer-async - Utiliser defer ou async sur les balises script

7. Performance JavaScript (FAIBLE-MOYEN)

• js-batch-dom-css - Grouper les changements CSS via des classes ou cssText
• js-index-maps - Construire une Map pour les recherches répétées
• js-cache-property-access - Mettre en cache les propriétés d'objets dans les boucles
• js-cache-function-results - Mettre en cache les résultats de fonctions dans une Map au niveau du module
• js-cache-storage - Mettre en cache les lectures de localStorage/sessionStorage
• js-combine-iterations - Combiner plusieurs filter/map en une seule boucle
• js-length-check-first - Vérifier la longueur du tableau avant une comparaison coûteuse
• js-early-exit - Retourner tôt des fonctions
• js-hoist-regexp - Déplacer la création de RegExp en dehors des boucles
• js-min-max-loop - Utiliser une boucle pour min/max au lieu de sort
• js-set-map-lookups - Utiliser Set/Map pour des recherches O(1)
• js-tosorted-immutable - Utiliser toSorted() pour l'immuabilité
• js-flatmap-filter - Utiliser flatMap pour mapper et filtrer en une seule passe
• js-request-idle-callback - Différer le travail non critique au temps d'inactivité du navigateur

8. Schémas avancés (FAIBLE)

• advanced-effect-event-deps - Ne pas mettre les résultats de useEffectEvent dans les dépendances d'effet
• advanced-event-handler-refs - Stocker les gestionnaires d'événements dans des refs
• advanced-init-once - Initialiser l'application une fois par chargement
• advanced-use-latest - useLatest pour des références de callback stables

Comment l'utiliser

Lisez les fichiers de règles individuels pour des explications détaillées et des exemples de code :

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

Chaque fichier de règle contient :

• Une brève explication de pourquoi c'est important
• Un exemple de code incorrect avec explication
• Un exemple de code correct avec explication
• Contexte supplémentaire et références

Document complet compilé

Pour le guide complet avec toutes les règles développées : AGENTS.md