react-patterns

Patrons React

Patrons idiomatiques React 18/19 pour construire des arbres de composants robustes, accessibles et performants.

Quand activer

• Écriture ou modification de composants fonctionnels React, de hooks personnalisés ou d'arbres de composants
• Révision de fichiers JSX/TSX
• Conception de la forme de l'état ou de la composition des composants
• Migration de composants à base de classes ou de code ancien utilisant forwardRef/useEffect
• Choix entre état local, état remonté, contexte et stores externes
• Travail avec des composants serveur / composants client (Next.js App Router, RSC)
• Implémentation de formulaires avec les actions React 19 ou les entrées contrôlées
• Câblage de la récupération de données avec TanStack Query / SWR / RSC

Principes fondamentaux

1. Le rendu est une fonction pure des props et de l'état

// Bon : dériver pendant le rendu
function Cart({ items }: { items: CartItem[] }) {
  const total = items.reduce((sum, i) => sum + i.price * i.qty, 0);
  return <span>{formatMoney(total)}</span>;
}

// Mauvais : état dérivé stocké séparément
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>;
}

L'état dérivé dans useEffect ajoute un cycle de rendu, peut se désynchroniser et obscurcit le flux de données.

2. Effets secondaires en dehors du rendu

Les effets, mutations, appels réseau et abonnements vivent dans les gestionnaires d'événements ou useEffect — jamais dans le corps du rendu.

3. Composition plutôt qu'héritage

React n'a pas de modèle d'héritage pour les composants. Composez avec children, les render props ou les props de composant.

Discipline des hooks

Voir rules/react/hooks.md pour l'ensemble complet des règles. Points clés :

• Uniquement au niveau racine, jamais conditionnel
• Nettoyer chaque abonnement, intervalle, écouteur
• Utiliser le mise à jour fonctionnel (setX(prev => prev + 1)) lorsque le nouvel état dépend de l'ancien
• Position par défaut : ne pas mémoïser — ajoutez useMemo/useCallback uniquement lorsqu'un profileur ou une chaîne de dépendances prouve que c'est utile
• Extrayez un hook personnalisé uniquement lorsque la même séquence de hooks apparaît dans 2 composants ou plus

Arbre de décision pour l'emplacement de l'état

Utilisé par un seul composant ?
  -> useState à l'intérieur

Utilisé par le parent + quelques descendants ?
  -> remonter à l'ancêtre commun le plus proche

Utilisé par des branches distantes ET lectures peu fréquentes (thème, auth, locale) ?
  -> React Context

Mises à jour fréquentes partagées dans tout l'arbre ?
  -> store externe (Zustand, Jotai, Redux Toolkit)

Dérivé d'un serveur ?
  -> bibliothèque d'état serveur (TanStack Query, SWR, fetch RSC)

La plupart des pages n'ont pas besoin de contexte ou de store global. Résistez à l'abstraction jusqu'à ce que le remontage dupliqué devienne pénible.

Composants serveur / client (RSC)

// Composant serveur - par défaut, asynchrone, n'envoie jamais de JS pour lui-même
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} />;
}

// Composant client - opt-in avec "use client"
"use client";
export function AddToCartButton({ productId }: { productId: string }) {
  const [pending, startTransition] = useTransition();
  return (
    <button
      disabled={pending}
      onClick={() => startTransition(() => addToCart(productId))}
    >
      {pending ? "Ajout..." : "Ajouter au panier"}
    </button>
  );
}

Limites :

• Serveur -> Client : passer des props sérialisables ou children
• Client -> Serveur : invoquer des actions serveur via <form action={...}> ou impérativement depuis des gestionnaires d'événements
• Ne jamais importer un composant serveur depuis un fichier de composant client — composez-les via children à la place

Suspense + Limites d'erreur

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

• Placez les limites Suspense près des données, pas à la racine de la route — révélez progressivement le contenu
• Error Boundary reste une API de classe ; utilisez react-error-boundary pour un wrapper compatible avec les hooks
• Une limite attrape les erreurs levées pendant le rendu, les cycles de vie et les constructeurs de ses enfants — PAS dans les gestionnaires d'événements ou le code asynchrone

Formulaires

Actions de formulaire React 19 (préférées pour le nouveau code)

"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: "Entrée invalide" };
  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}>Enregistrer</button>
      {state.error && <p role="alert">{state.error}</p>}
    </form>
  );
}

Entrées contrôlées

Utilisez le contrôle lorsque la valeur pilote une autre interface utilisateur, formate à chaque frappe ou implémente une validation en temps réel.

Formulaires complexes

Pour les formulaires en plusieurs étapes, les tableaux de champs dynamiques ou la validation croisée : utilisez une bibliothèque (React Hook Form, TanStack Form). Gérer votre propre état pour des formulaires dépassant la complexité triviale est un piège de maintenance.

Matrice de décision pour la récupération de données

Besoin	Outil
Données par requête dans Next.js App Router	RSC await fetch()
Cache client + mutations + invalidation	TanStack Query
Cache client léger + révalidation	SWR
Abonnements en temps réel	Événements envoyés par le serveur, WebSockets, ou l'API d'abonnement de la bibliothèque
Appel unique "tirer et oublier"	fetch() dans un gestionnaire d'événements

Évitez useEffect + fetch pour les données d'application — conditions de concurrence, pas de cache, pas de nouvelle tentative, pas d'intégration Suspense.

Recettes de composition

Slot via children

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

Slots nommés

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

Composants composés (état partagé via Context)

<Tabs defaultValue="profile">
  <Tabs.List>
    <Tabs.Trigger value="profile">Profil</Tabs.Trigger>
    <Tabs.Trigger value="settings">Paramètres</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Panel value="profile"><Profile /></Tabs.Panel>
  <Tabs.Panel value="settings"><Settings /></Tabs.Panel>
</Tabs>

Render prop / fonction-enfant

Utile lorsque le parent doit passer des paramètres au résultat rendu :

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

Alternative moderne : un hook (useData(id)) retournant la même forme — généralement plus propre.

Performance

Quand React.memo aide vraiment

Enveloppez un composant dans React.memo uniquement quand :

1. Il se rend à nouveau fréquemment
2. Ses props sont généralement identiques entre les rendus
3. Son rendu est mesurablement coûteux

React.memo ajoute une vérification d'égalité à chaque rendu. Si les props diffèrent sur la plupart des rendus, la vérification est une surcharge pure.

Éviter les cascades de rendu

• Descendez l'état plutôt que de le remonter si possible
• Divisez le contexte : un contexte par préoccupation, ainsi un changement de themeContext ne re-rend pas les consommateurs d'auth
• Utilisez useSyncExternalStore pour les bibliothèques d'état externes — requis pour un rendu concurrent sûr

Listes

• Fournissez des props key stables (identifiant de base de données, pas d'index de tableau)
• Virtualisez les longues listes avec @tanstack/react-virtual ou react-window une fois que le nombre d'éléments visibles dépasse ~50 avec des lignes non triviales

Composition priorisant l'accessibilité

• Rendez toujours un HTML sémantique (<button>, <a>, <nav>, <main>) avant d'utiliser les attributs role
• Chaque élément interactif doit être accessible au clavier
• Les entrées de formulaire ont besoin d'étiquettes — <label htmlFor> ou aria-label si étiqueté visuellement par une icône
• Gérez le focus lors des changements de route et de l'ouverture/fermeture de modale
• Exécutez axe dans les tests de composants (voir skills/react-testing)
• Lien croisé : skills/accessibility/SKILL.md couvre les critères WCAG et les bibliothèques de patrons

Routage

Cette compétence est agnostique en matière de routeur. Les patrons ci-dessus fonctionnent avec React Router, TanStack Router, Next.js App Router, Remix Router. Les patrons spécifiques au routeur (loaders, actions, mises en page imbriquées) suivent la documentation du routeur — ce sont des préoccupations de framework superposées au cœur de React.

Hors du champ d'application (sections de référence)

• Spécificités Next.js : Chargement de données App Router, Route Handlers, Middleware, Routes parallèles — préoccupation distincte, utilisez la documentation Next.js
• React Native : Les patrons spécifiques à la plateforme diffèrent suffisamment pour justifier une compétence react-native-patterns séparée (pas encore présente)
• Remix : Les conventions Loader/Action chevauchent RSC mais suivent la documentation Remix

Liens connexes

• Règles : rules/react/ — style de codage, hooks, patrons, sécurité, tests
• Compétences : react-performance pour l'ensemble de règles de performance dérivé de Vercel, frontend-patterns pour les préoccupations d'interface utilisateur multi-frameworks, accessibility, angular-developer pour la comparaison de frameworks
• Agents : react-reviewer pour la révision de code, react-build-resolver pour les erreurs de build/bundler
• Commandes : /react-review, /react-build, /react-test

Exemples

Hook personnalisé pour la recherche avec 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 optimiste avec 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: "moi" });
    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">Envoyer</button>
      </form>
    </>
  );
}

Fractionnement du contexte pour éviter les cascades de rendu

// Deux contextes : un change rarement, l'autre fréquemment
const ThemeContext = createContext<Theme>("light");
const NotificationsContext = createContext<Notification[]>([]);

// Un composant qui consomme uniquement ThemeContext ne se re-rend PAS lorsque les notifications changent