Guide de terrain de l'écosystème TanStack

TanStack est une collection de bibliothèques headless, type-safe et composables qui gèrent la récupération de données, le routage, les tableaux, les formulaires, la virtualisation et l’état client. L’écosystème est né de React Query, depuis renommé TanStack Query. Ses bibliothèques de données et d’interface utilisateur sont livrées avec des adaptateurs pour React, Vue, Solid, Svelte et Angular, tandis que son routeur et son framework full-stack ciblent React et Solid. TanStack n’est pas en soi un framework ; le projet décrit ses composants comme des utilitaires headless et composables, et un seul d’entre eux — TanStack Start — est un framework full-stack.

Si vous utilisez déjà TanStack Query et que vous voyez régulièrement mentionner Router, Start, Table, Form, Store, DB et AI, le problème concret est de comprendre ce que chacun fait, quel est son niveau de maturité, et quand y recourir plutôt qu’à la pile React par défaut (Next.js, React Router, Redux/Zustand, React Hook Form, Apollo, AG Grid). Ce guide cartographie l’écosystème bibliothèque par bibliothèque, fournit pour chacune une signature de code minimale, indique son niveau de maturité avec un numéro de version, et montre comment les pièces s’articulent. C’est une carte, pas un tutoriel — les étapes de configuration se trouvent dans la documentation officielle, dont les liens sont fournis tout au long du guide.

Qu’est-ce que TanStack, et pourquoi le concept de « headless » est-il important ?

TanStack est un ensemble de bibliothèques indépendantes qui partagent une règle de conception : la bibliothèque possède la logique, vous possédez le rendu. Chaque bibliothèque TanStack sépare l’état du balisage — la bibliothèque exécute la machine à états ; votre composant décide de l’apparence de l’interface. C’est ce que signifie « headless » en pratique : il n’y a pas de CSS TanStack à surcharger, pas de composant TanStack à étendre, et aucune opinion du fournisseur sur l’apparence de votre interface. TanStack Query est le point d’origine de la marque — il a été renommé depuis React Query lorsque l’écosystème s’est développé — bien que TanStack Table soit antérieur au changement de nom ; Query est donc l’origine popularisatrice, pas littéralement la première bibliothèque.

La philosophie commune est souvent résumée par « possédez votre code, pas votre framework ». Trois propriétés en découlent :

• Headless : logique sans interface utilisateur. Vous connectez l’état de la bibliothèque à n’importe quel balisage, système de design ou couche d’accessibilité que vous utilisez déjà.
• Cœur agnostique au framework : les bibliothèques de données et d’interface — Query, Table, Form, Virtual et Store — sont livrées avec des adaptateurs officiels pour React, Vue, Solid, Svelte et Angular. Le routage fait exception : TanStack Router et TanStack Start ciblent uniquement React et Solid.
• Composabilité plutôt que monolithes : chaque bibliothèque fonctionne seule ou en combinaison. Vous adoptez Query sans adopter Router, ou Table sans adopter Start.

La carte bibliothèque par bibliothèque

Chaque bibliothèque ci-dessous couvre ce qu’elle fait, ce qu’elle remplace, son niveau de maturité en juin 2026, et une signature de code minimale. Ces signatures représentent la surface d’API, pas un tutoriel de configuration — suivez les liens vers la documentation pour l’installation et la configuration.

TanStack Query — état serveur

TanStack Query gère l’état serveur asynchrone : récupération, mise en cache, re-récupération en arrière-plan, déduplication et mises à jour optimistes. Il remplace le pattern manuel fetch + useEffect qu’utilisaient la plupart des applications React à leurs débuts. Il est stable.

// @tanstack/react-query v5.101.0
const { data: users, isLoading, error } = useQuery({
  queryKey: ['users'],
  queryFn: () => fetch('/api/users').then((res) => res.json()),
});

Query est le point d’entrée le plus largement adopté dans l’écosystème et la modification offrant le meilleur retour sur investissement dans une base de code React existante, car il supprime les états de chargement et d’erreur codés manuellement sans toucher à vos couches de routage ou d’interface.

TanStack Router — routage type-safe

TanStack Router est un routeur côté client entièrement type-safe pour React et Solid. Les chemins de routes, les paramètres d’URL, les paramètres de recherche, le contexte de route et les données de loader sont tous typés de bout en bout, de sorte que le compilateur — et non l’utilisateur à l’exécution — détecte un lien avec une forme de paramètre incorrecte. Il remplace React Router pour les SPA et est stable.

// @tanstack/react-router v1.170.16
const Route = createFileRoute('/products')({
  validateSearch: (search) => ({
    category: (search.category as string) ?? 'all',
    page: Number(search.page ?? 1),
  }),
});

const { category, page } = Route.useSearch();

Router traite les paramètres de recherche d’URL comme un état typé et validé, ce qui rend les filtres, l’ordre de tri et la pagination partageables via l’URL et restaurables au rechargement. Cela résout une classe de bugs spécifique et reproductible : les replays de session de tableaux de bord SPA révèlent régulièrement des utilisateurs perdant leur état de filtre, de tri et de pagination au rechargement ou lors de la navigation arrière, lorsque cet état résidait en mémoire du composant plutôt que dans l’URL — exactement le mode de défaillance qu’éliminent les paramètres de recherche typés.

TanStack Table — grilles de données headless

TanStack Table gère la logique des grilles de données — définitions de colonnes, tri, filtrage, pagination, sélection de lignes, regroupement et visibilité des colonnes — tout en laissant chaque pixel de l’interface à votre charge. Il a établi le pattern headless dans l’écosystème React et remplace les bibliothèques de grilles avec opinions comme AG Grid et MUI DataGrid pour les équipes souhaitant un contrôle total du balisage. Il est stable, avec une ligne V9 en développement qui n’est pas encore la version latest publiée.

// @tanstack/react-table v8.21.3
const table = useReactTable({
  data,
  columns,
  getCoreRowModel: getCoreRowModel(),
});

L’instance Table gère l’état ; votre balisage rend ce que cet état décrit. Combiné avec Query pour la pagination et le filtrage côté serveur, il gère de grands ensembles de données sans tout charger côté client.

TanStack Form — formulaires typés

TanStack Form gère l’état des formulaires et la validation — erreurs au niveau des champs et du formulaire, validation synchrone et asynchrone, état de soumission — sans rien rendre lui-même. C’est le successeur headless de React Hook Form, et il est stable (v1).

// @tanstack/react-form v1.33.0
const form = useForm({
  defaultValues: { email: '', password: '' },
  onSubmit: async ({ value }) => { await loginUser(value); },
});

Les valeurs des champs, les schémas de validation et les charges utiles de soumission sont typés de bout en bout, et la validation asynchrone (vérification de la disponibilité d’un nom d’utilisateur, par exemple) est une fonctionnalité de première classe avec gestion du debouncing et de l’annulation par la bibliothèque.

TanStack Virtual — virtualisation de listes et de grilles

TanStack Virtual ne rend que les lignes ou colonnes actuellement dans la fenêtre d’affichage pour les grandes listes et grilles défilables, maintenant le DOM léger pendant que l’ensemble de données reste volumineux. Il vous fournit les mesures et les décalages ; vous rendez le balisage. Il remplace le windowing codé manuellement et les bibliothèques comme react-window et react-virtualized. Il est stable.

// @tanstack/react-virtual v3.14.3
const virtualizer = useVirtualizer({
  count: items.length,
  getScrollElement: () => parentRef.current,
  estimateSize: () => 48,
});

const rows = virtualizer.getVirtualItems();

useVirtualizer retourne les éléments virtuels visibles ainsi que la taille totale ; vous positionnez chaque élément en absolu par son décalage. Il se combine naturellement avec Table pour les grandes grilles de données — Table gère le modèle de lignes, Virtual ne conserve dans le DOM que les lignes visibles — de sorte qu’une liste de cinq mille lignes défile à pleine vitesse.

TanStack Store — état client

TanStack Store est un store réactif à granularité fine qui alimente les mécanismes internes de plusieurs autres bibliothèques TanStack et est exposé en tant que package autonome. Il offre une alternative à Zustand et Redux pour l’état client (non serveur). En tant que package autonome, il est en alpha (v0.11.0), donc traitez tout discours du type « remplace Zustand/Redux » avec ce niveau de maturité à l’esprit.

// @tanstack/store v0.11.0 + @tanstack/react-store
import { Store } from '@tanstack/store';
import { useStore } from '@tanstack/react-store';

const countStore = new Store(0);
// dans un composant :
const count = useStore(countStore);

La division du travail est le modèle mental utile : Query gère l’état serveur, Store gère l’état client. Pour la plupart des applications, Query combiné à une petite quantité de Store (ou votre outil d’état client existant) couvre l’ensemble de la surface d’état.

TanStack Start — framework full-stack

TanStack Start est un framework React full-stack construit sur TanStack Router. Il apporte le routage basé sur les fichiers, les fonctions serveur, le streaming SSR et TypeScript de bout en bout, tout en gardant les mécanismes sous-jacents visibles. Il se positionne face à Next.js et Remix. Start est en phase Release Candidate (ligne de versions actuelle 1.168.x), pas encore déclaré stable, et son support de React Server Components est disponible de manière expérimentale plutôt que comme valeur par défaut en production.

// @tanstack/react-start v1.168.26
import { createServerFn } from '@tanstack/react-start';

const getUser = createServerFn({ method: 'GET' })
  .validator((userId: string) => userId)
  .handler(async ({ data: userId }) => db.users.findById(userId));

Les fonctions serveur sont des fonctions typées et co-localisées qui s’exécutent sur le serveur mais s’appellent depuis les composants client comme n’importe quelle fonction asynchrone — les types circulent de la source de données au composant sans annotation manuelle, et il n’y a pas de couche API séparée à maintenir pour une récupération simple. Notez que le chemin d’import est @tanstack/react-start ; les anciens guides mentionnant @tanstack/start sont obsolètes.

TanStack DB — store client réactif

TanStack DB est un store réactif, orienté client, avec des collections, des requêtes en direct et des mutations optimistes. Vous définissez des collections, écrivez des requêtes contre elles, et tout composant observant une requête se re-rend lorsque les données sous-jacentes changent — qu’il s’agisse d’une synchronisation serveur, d’une mutation locale ou d’une mise à jour optimiste. Il se place devant votre propre backend ou API ; c’est une couche de store/synchronisation côté client, pas un remplacement de backend-as-a-service comme Firebase ou Supabase. Il est en bêta (v0.6.9).

DB répond au besoin au-delà du simple fetch-and-cache : les applications intensives en données avec des mises à jour en temps réel, un filtrage complexe côté client et un état multi-utilisateurs. La comparaison avec un « Firebase headless » est une analogie pour le modèle de requêtes réactives, pas une affirmation de substitution concernant l’infrastructure hébergée.

TanStack AI — primitives IA agnostiques au fournisseur

TanStack AI fournit des primitives headless pour les fonctionnalités alimentées par l’IA — gestion des réponses en streaming, état de conversation et interface unifiée entre les fournisseurs de modèles — sans vous enfermer dans un SDK ou un fournisseur unique. Il est en bêta, comme annoncé sur le blog TanStack, pas en alpha ou expérimental.

Les réponses en streaming (tokens arrivant de manière incrémentielle) sont gérées nativement, ce qui rend les interfaces de chat et de génération IA réactives. La valeur est architecturale : une couche agnostique au fournisseur vous permet de changer de fournisseur de modèle sans réécrire l’état de votre interface.

Le tableau de maturité

La maturité varie considérablement au sein de l’écosystème, et l’erreur la plus courante dans les aperçus de l’écosystème est de présenter des bibliothèques expérimentales comme établies. Cinq des neuf bibliothèques couvertes ici — Query, Router, Table, Form et Virtual — sont stables en juin 2026 ; Start est en phase Release Candidate avec React Server Components disponible de manière expérimentale ; DB et AI sont en bêta ; et Store est en alpha. Le tableau ci-dessous enregistre la version publiée et le statut de chaque bibliothèque.

Consultez la documentation liée pour connaître le statut de version actuel.

Comment les pièces s’assemblent

Les bibliothèques sont conçues pour se composer, et l’intégration centrale est celle des loaders de Router qui pré-récupèrent les données de Query afin qu’un composant se rende avec un cache déjà chargé. Un loader de route peut appeler queryClient.ensureQueryData avant le montage du composant ; au moment où il se rend, les données sont déjà en cache. Lorsque Start ajoute le SSR à ce pipeline, les données sont pré-chargées côté serveur et déshydratées, arrivant sous forme de HTML entièrement rendu dès la première requête.

// @tanstack/react-router v1.170.16 + @tanstack/react-query v5.101.0
const Route = createFileRoute('/users/$userId')({
  loader: ({ params }) =>
    queryClient.ensureQueryData({
      queryKey: ['user', params.userId],
      queryFn: () => fetchUser(params.userId),
    }),
  component: UserPage,
});

Trois connexions concrètes méritent d’être mentionnées :

1. Router → Query : les loaders de route pré-récupèrent les données Query, éliminant le flash de chargement au premier rendu.
2. Start → Router : Start est construit sur Router, de sorte que le modèle de routage typé et de loaders s’intègre directement dans le framework full-stack, avec l’ajout du SSR et de la déshydratation.
3. Table → Query : Table consomme les données paginées et filtrées de Query pour la pagination côté serveur, permettant à la grille de gérer de grands ensembles de données sans tout rapatrier côté client.

Choisir TanStack plutôt que les solutions établies

Choisissez TanStack Start pour les pages publiques qui doivent être indexées et partagées, et TanStack Router seul pour les tableaux de bord authentifiés où le SEO n’est pas pertinent et où la performance côté client est la priorité. Cette décision de stratégie de rendu est le premier choix architectural, et il précède tout choix de bibliothèque — c’est une décision produit, pas une préférence technique.

• Sites publics (pages marketing, blogs, produits de contenu) ont besoin du SSR. Les robots d’indexation n’exécutent pas JavaScript de manière fiable ; les Core Web Vitals comme LCP, CLS et INP sont des signaux de classement Google ; et les métadonnées Open Graph sont lues depuis la réponse serveur. Start livre du HTML entièrement rendu dès la première requête.
• Applications authentifiées (tableaux de bord, outils internes, portails clients) ne peuvent de toute façon pas être indexées, sont basées sur des sessions et avec état, et privilégient le time-to-interactive. Une SPA sur Router seul — sans la machinerie SSR de Start — est souvent plus légère.

Pour la question bibliothèque-versus-solution-établie, l’écosystème se cartographie proprement sur les valeurs par défaut React :

Quand ne pas utiliser TanStack

Le modèle headless et type-safe de TanStack est une valeur par défaut solide, mais représente un véritable inconvénient dans trois situations, et une carte honnête les nomme. Le modèle n’est pas adapté lorsque votre équipe a besoin de composants pré-stylisés prêts à l’emploi, lorsque votre vivier de recrutement connaît Redux et React Router mais pas TanStack, ou lorsque vous avez besoin d’un support stable de React Server Components en production dès aujourd’hui — car le support RSC dans Start est encore expérimental, et Next.js ainsi que React Hook Form restent des choix plus pragmatiques dans ces cas.

Plus précisément :

• Besoins en composants pré-stylisés : headless signifie que vous construisez l’interface. Si vous voulez une grille ou un formulaire qui soit visuellement abouti dès l’installation, AG Grid, MUI ou un kit de composants sera plus rapide.
• Familiarité de l’équipe et recrutement : davantage de développeurs connaissent Redux, React Router et Next.js. La courbe d’apprentissage et le vivier de recrutement plus restreint sont des coûts réels pour la montée en charge des équipes.
• RSC en production dès aujourd’hui : Next.js bénéficie d’années de tests en production pour React Server Components ; le support RSC de Start est expérimental en juin 2026.
• Bibliothèques en phase précoce : Store (alpha), DB (bêta) et AI (bêta) ne sont pas encore des valeurs par défaut en production. Adoptez-les en tenant compte de ce niveau de maturité, et surveillez la version et le statut dans la documentation officielle liée.

Au-delà des bibliothèques couvertes ici, TanStack maintient un niveau utilitaire — incluant Virtual, Pacer, Ranger et les DevTools — qui suit le même pattern headless et type-safe à une portée plus réduite.

Par où commencer

Adoptez Query en premier si ce n’est pas encore fait — c’est la modification offrant le meilleur retour sur investissement dans une base de code React et ne vous engage à rien d’autre. Optez pour Router sur une SPA greenfield plutôt que de migrer une application existante, et considérez Start comme le choix pour les nouveaux sites publics nécessitant le SSR, tout en surveillant son statut RC. Pour les bibliothèques en phase précoce — Store, DB et AI — laissez le tableau de maturité daté et la documentation officielle liée, et non l’engouement de l’écosystème, décider si une bibliothèque est prête pour le rôle que vous envisagez.

FAQ

Quelle est la différence entre TanStack Query et TanStack DB ?

TanStack Query gère l'état serveur asynchrone via la récupération, la mise en cache, la re-récupération en arrière-plan et la déduplication, traitant le serveur comme la source de vérité que le client reflète. TanStack DB est un store réactif, orienté client, avec des collections, des requêtes en direct et des mutations optimistes qui se place devant votre propre backend pour les applications intensives en données avec des mises à jour en temps réel et un filtrage complexe côté client. Query est stable ; DB est en bêta en juin 2026.

Puis-je utiliser les bibliothèques TanStack avec Vue, Svelte ou Angular plutôt qu'avec React ?

Oui, pour les bibliothèques de données et d'interface. Query, Table, Form, Virtual et Store sont livrés avec des adaptateurs officiels pour React, Vue, Solid, Svelte et Angular. Le routage fait exception : TanStack Router et le framework full-stack TanStack Start ciblent uniquement React et Solid. Ainsi, une équipe Vue ou Angular peut adopter Query et Table, mais ne peut pas utiliser TanStack Router pour un routage type-safe.

TanStack Start est-il prêt pour la production en tant que remplacement de Next.js ?

Pas entièrement, en juin 2026. TanStack Start est en phase Release Candidate sur la ligne de versions 1.168.x, pas encore déclaré stable, et son support de React Server Components n'est disponible qu'à titre expérimental plutôt que comme valeur par défaut en production. Si vous avez besoin d'un RSC stable en production dès aujourd'hui, Next.js bénéficie d'années de tests en production pour cette fonctionnalité. Start est un choix raisonnable pour les nouveaux sites SSR publics où un RSC expérimental est acceptable.

Dois-je adopter tout l'écosystème TanStack pour utiliser une seule bibliothèque ?

Non. Chaque bibliothèque TanStack est indépendante et composable, vous pouvez donc adopter Query sans Router, ou Table sans Start. Les bibliothèques s'intègrent lorsqu'elles sont utilisées ensemble (les loaders de route peuvent pré-récupérer les données Query, par exemple), mais aucune n'en requiert d'autres. Query est le point d'entrée le plus courant car c'est la modification offrant le meilleur retour sur investissement dans une base de code React existante et ne vous engage à rien d'autre dans l'écosystème.