Aller au contenu
Me contacter

Ouvert à un CDI · Métropole lilloise

Tous les articles
8 min de lecture

TanStack Query : gérer l’état serveur d’une application React

Dans une application de streaming, les favoris, les likes et la reprise de lecture appartiennent au serveur. À partir de Netflux Comedy, voici comment TanStack Query met ces données en cache, les rafraîchit après une modification et les efface à la déconnexion, et ce qui reste à Redux.

  • React
  • TanStack Query
  • React Query
  • Redux
  • TypeScript

Netflux Comedy est une plateforme de streaming de spectacles de stand-up que j’ai développée seul, en projet personnel, entre 2023 et 2024 : un front React en TypeScript et une API Symfony. On y parcourt les spectacles par humoriste, on ajoute des vidéos à sa liste, on s’abonne à des chaînes et on reprend une vidéo là où on l’avait laissée. Presque tout ce qu’affiche l’application vient donc de l’API et dépend de l’utilisateur connecté. Pour ces données, j’ai utilisé TanStack Query (anciennement React Query) en version 5, et gardé Redux Toolkit pour le reste. Ce découpage répond à une question que se pose tout projet React branché sur une API, celle de l’endroit où ranger ce qu’elle renvoie.

Pourquoi les données de l’API ne sont-elles pas un état comme les autres ?

Un favori n’appartient pas à l’interface. Il est enregistré en base, l’utilisateur peut l’ajouter depuis un autre appareil, et la liste affichée sur l’accueil n’est qu’une copie de ce que le serveur savait au moment de la requête. La documentation de TanStack Query parle d’état serveur pour ces données, stockées ailleurs, lues de façon asynchrone et susceptibles de changer sans que l’application le sache. Le texte saisi dans la barre de recherche ou le message de confirmation qui s’affiche après un clic relèvent au contraire de l’état d’interface, qui n’existe que dans le navigateur.

Ranger l’état serveur dans un store Redux classique oblige à recoder tout ce qui l’accompagne : chargement, erreurs, rafraîchissement, et surtout la synchronisation entre plusieurs copies d’une même donnée. Sur la plateforme SRS, ces copies avaient fini par se désynchroniser, comme le raconte l’article sur sa modernisation. TanStack Query prend ce travail à sa charge, tout comme RTK Query, son équivalent intégré à Redux Toolkit. Chaque requête dispose d’une entrée dans un cache partagé par tous les composants, et la librairie décide quand la recharger selon des règles qu’on peut ajuster.

Dans Netflux, le partage s’est fait ainsi :

  • TanStack Query reçoit les chaînes et leurs vidéos, la vidéo d’accueil, le profil, les favoris, les likes, les abonnements et les positions de lecture ;
  • Redux Toolkit garde le texte de recherche, ses résultats et la file des messages de confirmation (toasts).

Chaque donnée propre à l’utilisateur est exposée par un hook (useFavorite, useLike, useSubscription, useResume) qui regroupe la lecture de cette donnée et les actions qui la modifient. La page « Ma liste » n’a ainsi jamais à savoir d’où viennent les favoris qu’elle affiche.

Comment nommer et rafraîchir ce qu’on met en cache ?

Le cache de TanStack Query est indexé par des clés, des tableaux sérialisables. La documentation demande que la clé contienne toutes les variables dont dépend la fonction de requête. La page d’une chaîne dépend de son identifiant, qui doit donc figurer dans la clé. Chaque chaîne obtient ainsi sa propre entrée, et passer d’un humoriste à l’autre déclenche la bonne requête.

// Simplified example: one cache entry per channel
const { data: channel } = useQuery({
  queryKey: ['channels', channelId],
  queryFn: () => getChannelVideos(channelId),
})

// Data that only exists for a signed-in user
const { data: favorites, isLoading } = useQuery({
  queryKey: ['me', 'favorites'],
  queryFn: getUserFavorites,
  enabled: user !== null,
})

L’ordre des éléments dessine une hiérarchie. Ranger le profil, les favoris, les likes, les abonnements et les reprises sous un même préfixe ['me'] permet de viser toutes les données de l’utilisateur en une seule instruction, ce qui servira à la déconnexion. L’option enabled empêche quant à elle la requête de partir tant que personne n’est connecté. En v5, une requête désactivée qui n’a encore aucune donnée reste au statut pending ; c’est isLoading, vrai seulement pendant un premier chargement effectif, qui doit piloter l’indicateur de chargement.

Reste à savoir quand une donnée en cache est rechargée. Par défaut, staleTime vaut 0, si bien qu’une donnée est considérée comme périmée dès sa réception. Elle est alors rechargée en arrière-plan quand un composant qui l’utilise s’affiche, quand la fenêtre reprend le focus ou quand la connexion revient, et l’ancienne valeur reste affichée pendant ce temps. Pour un catalogue qui change peu, un staleTime de quelques minutes évite des requêtes inutiles ; pour des favoris modifiables depuis un autre appareil, le réglage par défaut convient. Une entrée qu’aucun composant n’utilise plus est supprimée au bout de cinq minutes (gcTime).

Que se passe-t-il quand l’utilisateur ajoute un favori ?

Une écriture passe par useMutation. Une fois la requête acceptée par l’API, deux options existent : écrire dans le cache la réponse renvoyée par le serveur, ou invalider les requêtes concernées. La première économise une requête quand l’API renvoie l’objet complet. La seconde, plus simple, marque ces requêtes comme périmées et recharge celles qui sont affichées, de sorte que la liste reflète ce que le serveur a réellement enregistré, tri et champs calculés compris.

// Simplified example: add a favorite, then refetch the list
function useAddFavorite() {
  const queryClient = useQueryClient()
  const { sendInformation, sendError } = useMessage()

  return useMutation({
    mutationFn: (videoId: string) => addFavorite(videoId),
    onSuccess: () => {
      sendInformation('Ajouté à votre liste')
      // Returning the promise keeps the mutation pending until the list is refetched
      return queryClient.invalidateQueries({ queryKey: ['me', 'favorites'] })
    },
    onError: () => sendError('Erreur lors de l’enregistrement'),
  })
}

Le return a son importance. Tant que la promesse de l’invalidation n’est pas résolue, la mutation reste en cours (isPending), et un bouton désactivé pendant l’envoi ne se réactive qu’une fois la liste à jour.

Afficher le favori avant la réponse de l’API

Sur un bouton d’ajout à sa liste, l’aller-retour réseau se remarque. Une mise à jour optimiste modifie le cache immédiatement, en pariant sur le succès de la requête, et garde de quoi revenir en arrière. La documentation la décrit en quatre temps : annuler les rechargements en cours pour qu’ils n’écrasent pas la valeur optimiste, sauvegarder l’état actuel, écrire la nouvelle valeur, puis restaurer la sauvegarde en cas d’échec et invalider dans tous les cas.

// Simplified example: optimistic add to the user's list
const favoritesKey = ['me', 'favorites']

useMutation({
  mutationFn: (videoId: string) => addFavorite(videoId),
  onMutate: async (videoId) => {
    // Stop in-flight refetches from overwriting the optimistic value
    await queryClient.cancelQueries({ queryKey: favoritesKey })
    const previous = queryClient.getQueryData<FavoriteItem[]>(favoritesKey)
    queryClient.setQueryData<FavoriteItem[]>(favoritesKey, (old = []) => [
      ...old,
      { videoId, pending: true },
    ])
    return { previous }
  },
  onError: (_error, _videoId, snapshot) => {
    queryClient.setQueryData(favoritesKey, snapshot?.previous)
  },
  onSettled: () => queryClient.invalidateQueries({ queryKey: favoritesKey }),
})

Cette technique a un coût, puisqu’il faut reproduire côté client la forme que le serveur aurait renvoyée et que le code grossit. Elle se justifie pour une action fréquente dont l’échec est rare, comme un favori ou un like. Pour une écriture qui peut être refusée pour une raison métier, une invalidation simple accompagnée d’un indicateur de chargement évite d’afficher un résultat qu’il faudra retirer.

Comment enregistrer une reprise de lecture ?

La reprise de lecture montre bien ce qui revient à chaque couche. Pendant la lecture, la position de la vidéo vit dans la propriété currentTime de l’élément video, et la recopier dans un état React à chaque mise à jour provoquerait des rendus sans intérêt. Elle ne devient un état serveur qu’au moment où l’utilisateur ferme le lecteur. Netflux l’envoie alors à l’API, qui l’enregistre pour cet utilisateur et cette vidéo.

// Simplified example: save the position when the player closes
const saveResume = useMutation({
  mutationFn: ({ videoId, time }: { videoId: string; time: number }) =>
    addResume(videoId, time),
  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['me', 'resumes'] }),
})

function closePlayer() {
  const time = videoRef.current?.currentTime
  if (user && time) saveResume.mutate({ videoId: video.videoId, time })
  setIsPlayerOpen(false)
}

L’API considère une vidéo comme terminée au-delà de 95 % de sa durée. En lecture, elle renvoie donc deux listes, les vidéos commencées et les vidéos terminées, qui alimentent les carrousels « Reprendre » et « Revoir » de l’accueil. Invalider ces listes après l’envoi suffit pour qu’en refermant le lecteur, l’utilisateur retrouve la vidéo dans le bon carrousel. À l’ouverture suivante, la position enregistrée est réappliquée à currentTime et la lecture reprend là où elle s’était arrêtée.

Que reste-t-il à Redux, ou à useState ?

La recherche de Netflux tolère les fautes de frappe grâce à Fuse.js, une librairie de recherche floue. Elle n’interroge pas l’API : elle lit les chaînes et leurs vidéos déjà présentes dans le cache de TanStack Query, cherche d’abord parmi les noms d’humoristes, puis dans le titre, la description et les tags des vidéos, et fusionne les deux résultats sans doublons. Le catalogue étant déjà chargé pour les carrousels de l’accueil, chaque frappe donne un résultat sans attendre le réseau.

Le texte saisi relève, lui, de l’état d’interface. Il est stocké dans Redux parce que deux endroits en ont besoin, la barre de recherche de l’en-tête et la page d’accueil, qui remplace ses carrousels par les résultats dès qu’une recherche est en cours. Les toasts suivent la même logique, puisqu’un hook peut les déclencher depuis n’importe quel composant.

Partager un état d’interface ne demande pas forcément Redux. Un Context React ou une librairie légère comme Zustand suffisent pour quelques valeurs partagées, et useState reste le choix naturel pour un état qui ne sort pas de son composant. Redux garde en général l’avantage quand cet état est riche, avec de nombreuses actions qu’on veut pouvoir suivre dans ses devtools.

Que vider quand l’utilisateur se déconnecte ?

Le cache de TanStack Query vit en mémoire tant que l’onglet reste ouvert, et une déconnexion ne le touche pas d’elle-même. Si un autre compte se connecte ensuite dans le même onglet, les favoris et les reprises du compte précédent sont encore en cache et peuvent s’afficher le temps que les nouvelles requêtes aboutissent. Dans Netflux, la déconnexion retire donc le token, puis supprime du cache le profil et les quatre listes propres à l’utilisateur.

Il y a deux façons de faire. queryClient.clear() vide tout le cache, données publiques comprises ; c’est simple, au prix d’un nouveau chargement du catalogue. removeQueries avec un préfixe ne retire que les données de l’utilisateur, à condition que leurs clés aient été rangées sous ce préfixe dès le départ, d’où l’intérêt de la hiérarchie vue plus haut.

// Simplified example: sign out without leaking the previous account's data
function logout() {
  localStorage.removeItem('userToken')
  queryClient.removeQueries({ queryKey: ['me'] }) // or queryClient.clear()
  navigate('/')
}

Ajouter l’identifiant de l’utilisateur aux clés est une autre option, qui donne à chaque compte ses propres entrées. Elle ne dispense pas du nettoyage, car les données du compte précédent restent en mémoire jusqu’à ce que gcTime les supprime.