Vous avez déjà écrit du code React pour chercher des données et vous êtes retrouvé avec 80 lignes de useEffect, useState et logique d’erreur pour afficher une simple liste d’utilisateurs ? Ce guide est pour vous.

C’est quoi le « server state » ?

Avant de plonger dans TanStack Query, il faut comprendre un concept clé : la différence entre client state et server state.

Le client state, c’est ce qui vit dans votre application (Une modale ouverte ou fermée, l’onglet actif, le texte tapé dans un formulaire). Vous le contrôlez totalement, il ne change pas « tout seul ».

Le server state, c’est différent. Ce sont des données qui vivent sur un serveur distant : la liste des utilisateurs en base, les commandes d’un client, les articles d’un blog. Elles peuvent changer à tout moment (un autre utilisateur les modifie), devenir périmées, ou échouer à se charger. useState et useEffect ne sont tout simplement pas conçus pour ça, et c’est là que TanStack Query entre en jeu.

Le problème, puis la solution

Voici comment on fetche des données en React sans bibliothèque :

Sans TanStack Query

Ce code fonctionne, mais il a des problèmes silencieux : pas de cache (si l’utilisateur revient sur le même profil, tout est re-fetché), pas de retry automatique si la requête échoue, et si l’utilisateur navigue rapidement entre profils, les réponses peuvent arriver dans le désordre (race condition).

Avec TanStack Query

Même résultat visuel, mais en coulisses : les race conditions sont gérées, les données sont mises en cache, TanStack Query réessaie automatiquement 3 fois en cas d’erreur, et les données se rafraîchissent quand l’utilisateur revient sur l’onglet.

Les vrais problèmes qu’il résout

Le cache intelligent (moins d’appels API)

TanStack Query stocke les résultats de chaque requête dans un cache global identifié par une queryKey. Si deux composants différents demandent les mêmes données, une seule requête est effectuée. Si l’utilisateur revisite une page dont les données sont encore fraîches, aucun appel n’est fait: les données en cache s’affichent instantanément.

C’est un bénéfice direct pour votre API : moins de charge, moins de coûts si vous êtes sur une API facturée à l’usage, et une meilleure expérience utilisateur.

Vous pouvez aussi contrôler combien de temps les données restent considérées comme fraîches avant qu’un nouvel appel soit déclenché :

La synchronisation en arrière-plan (background refetch)

Quand l’utilisateur revient sur un onglet, TanStack Query vérifie discrètement si les données ont changé. L’utilisateur voit les données en cache instantanément, puis les nouvelles arrivent en douceur si besoin. Ce comportement s’appelle stale-while-revalidate.

Les retries automatiques

Si une requête échoue (erreur réseau, serveur indisponible), TanStack Query réessaie automatiquement jusqu’à 3 fois, avec un délai exponentiel entre chaque tentative.

Le nettoyage automatique du cache (gcTime)

Plus votre application tourne, plus le cache peut grossir surtout si vous chargez des listes paginées ou des profils utilisateurs à la volée. Sans nettoyage, ça finit par peser sur la mémoire.

TanStack Query gère ça avec gcTime (garbage collection time). Par défaut, quand un composant est démonté (l’utilisateur quitte la page), ses données restent en cache pendant 5 minutes, puis sont automatiquement supprimées si aucun autre composant ne les utilise.

Vous n’avez rien à faire pour activer ce comportement, il est là par défaut.

La gestion des timeouts

TanStack Query ne gère pas les timeouts nativement, mais il s’appuie sur AbortController (une API native du navigateur) pour les implémenter proprement. TanStack passe automatiquement un signal dans la queryFn, ce qui permet de combiner annulation et timeout :

Et pour afficher un message adapté selon le type d’erreur :

Vous pouvez aussi désactiver les retries automatiques spécifiquement sur les timeouts, pour ne pas re-solliciter une API déjà lente :

Les mutations (écriture de données)

Pour créer, mettre à jour ou supprimer des données, TanStack Query propose useMutation, qui gère les états de chargement et peut invalider le cache automatiquement après une opération réussie.

La pagination et le chargement infini

TanStack Query inclut useInfiniteQuery pour le chargement infini (le fameux « Charger plus »), et une gestion propre de la pagination côté client.

Compatible React, Angular, Vue et Svelte

TanStack Query ne se limite pas à React. Il existe des adaptateurs officiels pour Angular, Vue et Svelte. Pour les détails d’installation et de configuration selon votre framework, référez-vous à la documentation officielle.

Pour React :

La configuration de base consiste à envelopper votre app dans un QueryClientProvider :

Quand l’utiliser ?

TanStack Query est utile si vous avez plusieurs composants qui consomment les mêmes données d’une API, si vous voulez du cache et des retries sans les implémenter vous-même, ou si vos données doivent rester à jour automatiquement.

Ce n’est probablement pas nécessaire si votre app ne fait que quelques requêtes très simples et que les données ne changent jamais.

Un bon indicateur : si vous copiez-collez la même logique useState + useEffect pour chaque appel API, c’est le moment d’essayer TanStack Query.

Conclusion

TanStack Query comble un manque précis : la gestion du server state. En quelques lignes, vous obtenez le cache, les retries, la synchronisation en arrière-plan, et vous éliminez le boilerplate répétitif de chaque appel API. Le cache intelligent réduit aussi significativement le nombre d’appels vers votre API, ce qui allège la charge serveur et améliore les performances globales. Disponible pour React, Angular, Vue et Svelte, c’est un outil qui s’intègre facilement dans n’importe quelle stack moderne.

[/vc_column_text]