ADR-003 · TanStack React Query pour le state serveur¶

Attribut	Valeur
Statut	✅ Accepté
Date	Janvier 2024
Décideurs	Équipe technique Primatch
Tags	frontend, state-management, data-fetching

Contexte¶

La SPA React a besoin de gérer les données provenant de l'API (state serveur) de façon efficace : cache, rechargement, mutations, synchronisation. La tentation naturelle est d'utiliser Redux ou Zustand pour tout gérer, mais cela crée une duplication : les données API dans un store local.

Options évaluées¶

Option	Pour	Contre
Redux + RTK Query	Standard, large communauté	Boilerplate important, complexité
Zustand + fetch manuel	Simple, léger	Pas de cache, rechargement manuel
TanStack React Query	Cache intelligent, mutations, déduplique requêtes	Courbe d'apprentissage hooks
SWR	Simple	Moins de fonctionnalités que React Query

Décision¶

Nous utilisons TanStack React Query v5 avec la configuration :

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 1,
      refetchOnWindowFocus: false,
    },
  },
});

Conséquences¶

✅ Avantages¶

Cache automatique : les données API ne sont pas refetchées inutilement
Déduplification : plusieurs composants qui demandent la même donnée = 1 seul appel
Mutations optimistes : UX réactive sans attendre la réponse serveur
DevTools intégrés pour le debugging

⚠️ Inconvénients¶

Pas pour le state UI : React Query ne gère que le state serveur. Pour le state local (modales, thème), utiliser useState/useReducer

Convention¶

Tous les hooks de data fetching doivent être dans hooks/ et préfixés par use
Exemple : useMatches(), useTournament(id), useCreateMatch()
Ne jamais utiliser useEffect + useState pour fetcher des données API