Bases de TanStack Query : requêtes, mise en cache, mutations et invalidation
Découvrez comment useQuery, queryKey, staleTime, gcTime, useMutation et invalidation s’associent pour gérer l’état du serveur dans React, sans avoir à écrire manuellement des effets fetch.
Sources: Started with React Query
TanStack Query, anciennement React Query, gère les données provenant d’un serveur. Le nom a changé car cette bibliothèque fonctionne désormais également en dehors de React, dans Svelte, Vue et Solid. On peut la décrire brièvement comme un gestionnaire d’état pour l’état serveur.
État serveur versus état client
L’état serveur correspond aux données issues d’un backend ou d’une API externe : utilisateurs, produits, articles, commentaires. Il se trouve en dehors de l’application, ce qui signifie que celle-ci ne le contrôle pas entièrement. Il peut changer sans que l’application ne s’en aperçoive, devenir obsolète, et ne peut être consulté qu’à travers une requête asynchrone.
L’état client appartient à l’application elle-même. Par exemple, le fait qu’un modal soit ouvert n’existe que dans le navigateur, comme dans const [isModalOpen, setIsModalOpen] = useState(false). Zustand, Redux et Jotai sont les outils habituels pour gérer ce type d’état.
La méthode manuelle et son coût
En l’absence d’une bibliothèque, la récupération des utilisateurs commence généralement par trois éléments d’état.
const [users, setUsers] = useState([])
const [loading, setLoading] = useState(false)
const [error, setError] = useState(null)
Ensuite, un effet gère le chargement.
useEffect(() => {
async function fetchUsers() {
try {
setLoading(true) const res = await fetch(
"https://jsonplaceholder.typicode.com/users"
) const data = await res.json() setUsers(data)
} catch (err) {
setError(err)
} finally {
setLoading(false)
}
} fetchUsers()
Les utilisateurs sont récupérés, stockés dans l’état, un indicateur de chargement est activé et les erreurs sont capturées. À mesure que l’application se développe, ce schéma se répète partout, et chaque partie doit gérer les états de chargement et d’erreur, le cache, la récupération de données, la récupération en arrière-plan, la synchronisation et les tentatives de réparation. Multipliez cela sur une grande base de code et le résultat est un code embrouillé.
La même chose avec une requête
Un seul crochet remplace le code générique.
function Users() {
const {
data,
isLoading,
error
} = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Le composant se divise ensuite en fonction de l’état.
if (isLoading) {
return <p>Loading...</p>
} if (error) {
return <p>Something went wrong</p>
} return (
<ul>
{data.map(user => (
<li key={user.id}>
{user.name}
</li>
))}
</ul>
)
}
TanStack Query gère l’infrastructure liée aux données serveur. Son principal avantage par rapport à useEffect combiné à useState réside dans son cache intégré. Une fois les données reçues, elles sont stockées dans le cache et peuvent être réutilisées ultérieurement, ce qui réduit les requêtes API inutiles. Les états de chargement, de succès et d’erreur sont suivis automatiquement, il n’est donc pas nécessaire d’écrire ou de maintenir manuellement de la logique.
Installation
Installez le paquet.
npm install @tanstack/react-query
Créez ensuite un QueryClient et fournissez-le à l’application.
const queryClient = new QueryClient();
root.render(
<QueryClientProvider client={queryClient}>
<App />
</QueryClientProvider>
);
Lecture des données avec useQuery
L’hook useQuery gère les lectures, c’est-à-dire tout ce qui récupère des données serveur. Une appelation de base ressemble à ceci :
const { data,
isPending,
error } = useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Ce composant prend un objet options, et deux propriétés sont les plus importantes : queryFn et queryKey.
queryFn est la fonction que TanStack Query appelle pour récupérer les données. Elle renvoie les données directement ou sous forme de Promise, et en cas d’échec, elle doit lancer une exception ou renvoyer une Promise rejetée.
async function fetchUsers() {
const res = await fetch("/api/users")
if (!res.ok) {
throw new Error("Failed to fetch users")
}
return res.json()
}
Puis il se branche sur le crochet :
useQuery({
queryKey: ["users"],
queryFn: fetchUsers
})
Le queryKey identifie de manière unique une requête et ses données mémorisées. Les variables utilisées par queryFn devraient généralement figurer dans la clé. Par exemple, ["users"] pourrait désigner tous les utilisateurs, ["todo", 1] la tâche à faire ayant l’ID 1, et ["products", "laptops"] les ordinateurs portables.
L’hook renvoie un objet contenant l’état de la requête (chargement, erreur ou succès), les données ainsi que les fonctions permettant de la récupérer à nouveau.
Comment le cache aide
C’est là que la bibliothèque se révèle utile. Les données récupérées sont stockées automatiquement et réutilisées pour éviter des appels redondants, ce qui améliore les performances et réduit le temps nécessaire pour afficher les résultats.
Disons que le composant A demande ["users"]. TanStack Query récupère et met en cache le résultat. Plus tard, le composant B demande la même clé et la bibliothèque constate que les données sont déjà en cache. Au lieu que chaque composant garde sa propre copie, TanStack Query gère une seule copie en cache de l’état du serveur. C’est l’une des plus grandes différences entre une simple utilisation de fetch() et cette bibliothèque.
staleTime et gcTime
staleTime répond à une question : pendant combien de temps ces données doivent-elles être considérées comme fraîches ?
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
staleTime: 60,000 // 60 seconds
})
Avec cette configuration, les données restent à jour pendant les 60 premières secondes. Après une minute, elles deviennent obsolètes, ce qui permet de déclencher un nouveau chargement ainsi qu’un renouvellement en arrière-plan. Être obsolète ne signifie pas être supprimé, bien que les données puissent être dépassées. Une fois obsolètes, elles peuvent être rechargées lorsque quelque chose le déclenche, comme lorsque la fenêtre redevient en premier plan ou qu’un composant est chargé.
Ignorer le statut d’obsolétude entraîne des requêtes inutiles lorsque les utilisateurs reviennent sur une page.
User visits page
↓
Fetch users
↓
User navigates away
↓
User comes back
↓
Fetch users again
Si rien ne change, la deuxième demande est inutile. Une fenêtre de fraîcheur plus longue permet d’éviter cela :
staleTime: 5 * 60 * 1000
Cela marque les données comme fraîches pendant cinq minutes. N’oubliez pas que staleTime contrôle la fraîcheur et n’est pas un intervalle de rechargement.
Il y a aussi gcTime, le temps de collecte des déchets. Il détermine combien de temps les données en mémoire cache inactives et non surveillées restent dans la mémoire avant d’être collectées.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
gcTime: 60000
})
En résumé, staleTime indique la durée pendant laquelle les données restent à jour, tandis que gcTime indique la durée pendant laquelle les entrées de cache inutilisées persistent. Ils résolvent des problèmes différents.
Réchargement
Les requêtes obsolètes peuvent être réchargées lorsque un composant est chargé, que la fenêtre redevient active ou que le réseau se reconnecte, et ces comportements sont configurables. Un réchargement manuel est également possible.
const { refetch } = useQuery(...)
refetch()
Il est également possible de réaliser des sondages.
useQuery({
queryKey: ["users"],
queryFn: fetchUsers,
refetchInterval: 30,000
})
Lorsque la requête est active, elle est rechargée approximativement toutes les 30 secondes. Ce rechargement remplace les données obsolètes par des données fraîches provenant du backend.
Changer les données avec useMutation
Jusqu’à présent, tout consistait à lire des données. La création, la mise à jour ou la suppression (POST, PUT, PATCH, DELETE) s’effectue via le hook useMutation. Par exemple, voici comment créer un utilisateur : il faut d’abord définir la fonction de mutation.
async function createUser(user) {
const response = await fetch(
"https://jsonplaceholder.typicode.com/users",
{
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(user),
}
);
if (!response.ok) {
throw new Error("Failed to create user");
}
return response.json();
}
Ensuite, il est transmis à useMutation.
import { useMutation } from "@tanstack/react-query";
function CreateUser() {
const mutation = useMutation({
mutationFn: createUser,
});
return (
<button
onClick={() =>
mutation.mutate({
name: "John Doe",
email: "john@example.com",
})
}
disabled={mutation.isPending}
>
{mutation.isPending ? "Creating..." : "Create User"}
</button>
);
}
export default CreateUser;
Un clic sur le bouton déclenche la mutation via mutation.mutate().
Button click
↓
mutation.mutate(user)
↓
createUser(user)
↓
POST request
↓
Server
Remarquez que createUser() n’est jamais appelé directement. Le composant appelle mutation.mutate() et TanStack Query exécute cette fonction.
Les mutations comportent des indicateurs d’état, tout comme les requêtes.
const {
mutate,
isPending,
isSuccess,
isError,
error,
data,
} = useMutation({
mutationFn: createUser,
});
Ils gèrent l’interface utilisateur.
<button
onClick={() => mutate({ userName: "delfina ghimire" })}
disabled={isPending}
>
{isPending ? "Creating..." : "Create user"}
</button>
Lorsque mutate() est exécuté, la mutation passe par plusieurs états :
isPending: la mutation est en cours d’exécution.isSuccess: elle s’est terminée avec succès.isError: elle a échoué.data: le résultat d’une mutation réussie.error: les détails en cas d’échec.mutate: le déclencheur, qui accepte les variables pour la fonction de mutation.
Cela rend simple la fourniture de retours d’information lors d’une création, d’une mise à jour ou d’une suppression.
QueryClient et invalidation
QueryClient est un objet central qui gère le cache et coordonne le comportement des requêtes et des mutations. Il a été créé initialement avec new QueryClient(), et à l’intérieur d’un composant on y accède via useQueryClient(). Il permet d’invalider les requêtes, de mettre à jour les données en cache, de supprimer les données en cache, de réinitialiser les requêtes et de précharger des données. Une appelation typique est queryClient.invalidateQueries({ queryKey: ["users"] }).
L’invalidation est particulièrement importante après les mutations. Lorsqu’une mutation modifie les données serveur, les requêtes associées peuvent contenir des résultats obsolètes, et leur invalidation les marque comme périmées afin qu’elles puissent être rechargées. Supposons que le cache contienne deux utilisateurs :
[
{ id: 1, userName: "delfina ghimire" },
{ id: 2, userName: "spiderman ghimire" },
]
Un nouvel utilisateur est alors créé.
mutation.mutate({
userName: "ironman ghimire",
});
Le serveur compte maintenant trois utilisateurs, mais le cache affiche encore deux. La requête ["users"] peut être marquée comme obsolète. Tout d’abord, on obtient le client :
const queryClient = useQueryClient();
La mutation est alors annulée en cas de succès.
const mutation = useMutation({
mutationFn: createUser,
onSuccess: () => {
queryClient.invalidateQueries({
queryKey: ["users"],
});
},
});
Le flux se déroule comme suit :
Create Users (Mutation)
↓
Server data changes
↓
Invalidate ["users"]
↓
Query becomes stale
↓
Refetch
↓
UI gets fresh data
Pour bien distinguer les termes : invalidate marque les données en mémoire tampon comme obsolètes, tandis que refetch les charge à nouveau immédiatement. L’invalidation d’une requête active déclenchera généralement un rechargement automatique.
Le tableau d’ensemble
Tous ces éléments forment un ensemble cohérent :
- TanStack Query gère les données serveur.
- La lecture s’effectue à l’aide de
useQuery. - Les données récupérées sont stockées dans le cache de requêtes.
staleTimedétermine quand les données en mémoire tampon sont considérées comme fraîches.gcTimedéfinit la durée pendant laquelle les entrées de cache inutilisées restent stockées.- Le rechargement décide du moment où les données sont chargées à nouveau.
- La création, la mise à jour et la suppression s’effectuent via
useMutation. - QueryClient coordonne les requêtes, les mutations et le cache.
- L’invalidation d’une requête indique que les données en mémoire tampon sont dépassées.
Lorsque ces relations sont claires, il devient beaucoup plus facile de comprendre la bibliothèque.