react-patterns

Modèles React (React Patterns)

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

Quand activer

• Écrire ou modifier des fonctions composants React, des hooks personnalisés ou des arbres de composants
• Réviser des fichiers JSX/TSX
• Concevoir la forme de l'état ou la composition de composants
• Migrer des composants classe ou du code ancien utilisant forwardRef/useEffect de manière intensive
• Choisir entre état local, état remonté, contexte et stores externes
• Travailler avec des composants serveur / composants client (Next.js App Router, RSC)
• Implémenter des formulaires avec les actions React 19 ou des entrées contrôlées
• Câbler le chargement de données avec TanStack Query / SWR / RSC

Principes fondamentaux

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

// Bien : 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>;
}

// Mal : é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 hors 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 composants.

Discipline des hooks

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

• Toujours au niveau supérieur, jamais conditionnellement
• Nettoyer chaque abonnement, intervalle, écouteur
• Utiliser la mise à jour fonctionnelle (setX(prev => prev + 1)) lorsque le nouvel état dépend de l'ancien
• Position par défaut : ne pas mémoriser — ajouter useMemo/useCallback uniquement quand un profileur ou une chaîne de dépendances prouve que c'est nécessaire
• Extraire 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 vers l'ancêtre commun le plus proche

Utilisé entre branches éloignées ET lectures peu fréquentes (thème, auth, locale) ?
  -> Contexte React

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 la remontée d'état devienne douloureuse.

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 les actions serveur via <form action={...}> ou impérativement depuis les gestionnaires d'événements
• Ne jamais import un composant serveur depuis un fichier de composant client — les composer via children plutôt

Suspense + Limites d'erreur

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

• Placer les limites Suspense près des données, pas à la racine de la route — dévoiler progressivement le contenu
• Error Boundary reste une API de classe ; utiliser react-error-boundary pour un wrapper compatible avec les hooks
• Une limite d'erreur intercepte 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 (recommandé 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

Utiliser des entrées contrôlées lorsque la valeur pilote une autre UI, formate chaque frappe ou implémente une validation en temps réel.

Formulaires complexes

Pour les formulaires multi-étapes, les tableaux de champs dynamiques ou la validation croisée de champs : utiliser une bibliothèque (React Hook Form, TanStack Form). Gérer manuellement l'état pour des formulaires dépassant une complexité triviale est un piège de maintenance.

Matrice de décision pour le chargement 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 + revalidation	SWR
Abonnements en temps réel	Server-Sent Events, WebSockets, ou l'API d'abonnement de la lib
Appel unique "fire-and-forget"	fetch() dans un gestionnaire d'événements

Évitez useEffect + fetch pour les données d'application — courses de données, pas de cache, pas de retry, pas d'intégration Suspense.

Recettes de composition

Slot via children

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

Slots nommés

<Page header={<Nav />} sidebar={<Filtres />}>
  <Resultats />
</Page>

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

<Tabs defaultValue="profil">
  <Tabs.List>
    <Tabs.Trigger value="profil">Profil</Tabs.Trigger>
    <Tabs.Trigger value="parametres">Paramètres</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Panel value="profil"><Profile /></Tabs.Panel>
  <Tabs.Panel value="parametres"><Parametres /></Tabs.Panel>
</Tabs>

Render prop / fonction-enfant

Utile lorsque le parent doit passer des paramètres au rendu produit :

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

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

Performance

Quand React.memo aide vraiment

Envelopper un composant dans React.memo uniquement quand :

1. Il se re-rend fréquemment
2. Ses props sont généralement les mêmes 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 la plupart du temps, la vérification est une surcharge pure.

Éviter les cascades de rendu

• Descendre l'état plutôt que le remonter quand c'est possible
• Fractionner le contexte : un contexte par préoccupation, de sorte qu'un changement de themeContext ne re-rende pas les consommateurs d'auth
• Utiliser useSyncExternalStore pour les bibliothèques d'état externes — requis pour un rendu concurrent sûr

Listes

• Fournir des props key stables (id de base de données, pas un index de tableau)
• Virtualiser 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 axée sur l'accessibilité

• Toujours rendre du 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 nécessitent des labels — <label htmlFor> ou aria-label si visuellement labelisé par une icône
• Gérer le focus lors des changements de route et l'ouverture/fermeture de modales
• Exécuter 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 motifs

Routage

Ce skill est agnostique en matière de routeur. Les motifs ci-dessus fonctionnent avec React Router, TanStack Router, Next.js App Router, Remix Router. Les motifs spécifiques aux routeurs (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 périmètre (sections de pointage)

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

Liens connexes

• Règles : rules/react/ — style de codage, hooks, motifs, sécurité, tests
• Skills : react-performance pour l'ensemble de règles de performance dérivé de Vercel, frontend-patterns pour les préoccupations UI transversales, accessibility, angular-developer pour 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 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 qui change rarement, un qui change 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