deckardger/bonnes-pratiques-intégration-tanstack

Que fait bonnes-pratiques-intégration-tanstack ?

Bonnes pratiques pour intégrer TanStack Query avec TanStack Router et TanStack Start. Modèles pour le flux de données full-stack, le SSR et la coordination du cache.

Aperçu

Cette compétence définit des modèles éprouvés pour intégrer TanStack Query (gestion des données asynchrones) avec TanStack Router (routage côté client) et TanStack Start (framework full-stack). Elle se concentre sur la garantie d'un flux de données fluide du serveur au client, en particulier dans les applications SSR et hydratées.

Modèles clés

1. Préremplissage des requêtes dans le chargeur de route

Utilisez les loaders de TanStack Router pour préremplir le cache de TanStack Query côté serveur avant que la page ne soit rendue.

import { queryOptions } from '@tanstack/react-query';
import { createFileRoute } from '@tanstack/react-router';

const postQueryOptions = (id: string) =>
  queryOptions({
    queryKey: ['posts', id],
    queryFn: () => fetch(`/api/posts/${id}`).then(res => res.json()),
  });

export const Route = createFileRoute('/posts/$postId')({
  loader: async ({ context: { queryClient }, params: { postId } }) => {
    await queryClient.prefetchQuery(postQueryOptions(postId));
  },
  component: PostComponent,
});

2. Hydratation du cache côté client

Utilisez dehydrate et HydrationBoundary pour transférer l'état du cache du serveur au client, évitant ainsi les appels API redondants.

// Dans votre configuration de route ou de page
import { dehydrate, HydrationBoundary } from '@tanstack/react-query';

// Dans le chargeur côté serveur
const dehydratedState = dehydrate(queryClient);

// Dans le composant racine
<HydrationBoundary state={dehydratedState}>
  <YourApp />
</HydrationBoundary>

3. Coordination des mutations et des requêtes

Utilisez useMutation avec invalidation pour maintenir le cache cohérent après les modifications de données.

import { useMutation, useQueryClient } from '@tanstack/react-query';

export const useAddPost = () => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: (newPost) => fetch('/api/posts', { method: 'POST', body: JSON.stringify(newPost) }),
    onSuccess: () => {
      // Invalider et recharger les requêtes 'posts'
      queryClient.invalidateQueries({ queryKey: ['posts'] });
    },
  });
};

4. Synchronisation du cache avec TanStack Start

Tirez parti de TanStack Start pour la génération de données côté serveur et l'hydratation transparente du cache, garantissant ainsi que les données sont disponibles immédiatement lors du rendu côté client.

// Exemple avec TanStack Start
import { useQuery } from '@tanstack/react-query';
import { createServerFn } from '@tanstack/start';

const fetchPosts = createServerFn('GET', async () => {
  return fetch('https://api.example.com/posts').then(res => res.json());
});

// Dans le composant
function Posts() {
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => fetchPosts(),
  });
  return <div>{/* rendu des posts */}</div>;
}

Plateformes prises en charge

• TanStack Query (v5+)
• TanStack Router (v1+)
• TanStack Start (v1+)
• React (18+)
• Vite (en tant que bundler)

Avantages

• Performances : Évite les appels API redondants grâce à l'hydratation du cache.
• Cohérence : Maintient le cache synchronisé entre les mutations et les requêtes.
• SSR : Garantit que les données sont disponibles côté serveur pour un rendu initial complet.
• Maintenabilité : Sépare la logique de chargement des données des composants.

Bonnes pratiques supplémentaires

• Utilisez toujours queryOptions pour définir les options de requête ; cela améliore la sécurité des types et la réutilisabilité entre les chargeurs et les composants.
• Évitez les appels fetch directs dans les composants ; utilisez queryFn dans queryOptions pour maintenir une logique centralisée.
• Invalidez les requêtes par lots pour réduire les rechargements inutiles.
• Utilisez staleTime approprié pour éviter les rechargements inutiles lors des navigations.

Références

• Documentation TanStack Query
• Documentation TanStack Router
• Documentation TanStack Start