Débuter avec TanStack DB pour les interfaces réactives

Créer des interfaces réactives ne devrait pas vous obliger à choisir entre performance et simplicité. Pourtant, chaque mise à jour d’état dans les applications JavaScript modernes déclenche des re-rendus en cascade, une mémoïsation complexe et des mises à jour optimistes lourdes en code répétitif. TanStack DB change complètement cette équation.

Cet article présente TanStack DB—une couche de base de données côté client qui étend TanStack Query avec des collections, des requêtes live et un flux de données différentiel pour des mises à jour en quelques fractions de milliseconde. Vous découvrirez comment il simplifie la gestion d’état par rapport à Redux ou au cache manuel, et comment l’adopter progressivement dans vos projets existants.

Note : TanStack DB est actuellement en version bêta (fin 2025). Bien que les APIs puissent évoluer, il est suffisamment stable pour l’exploration et l’adoption progressive dans des fonctionnalités non critiques.

Qu’est-ce que TanStack DB ?

TanStack DB est un store client réactif qui s’appuie sur TanStack Query. Alors que TanStack Query excelle dans la récupération et la mise en cache de l’état serveur, il traite chaque résultat de requête comme une entrée de cache isolée. TanStack DB ajoute la couche relationnelle manquante—permettant des jointures, des filtres et des mises à jour réactives à travers l’ensemble de votre graphe de données.

La magie réside dans le flux de données différentiel (differential dataflow), une technique qui ne recalcule que les parties des requêtes qui ont réellement changé. Cela signifie que la mise à jour d’une ligne dans une collection de 100 000 éléments ne prend que 0,7 ms sur un M1 Pro—suffisamment rapide pour éliminer complètement les saccades d’interface.

Concepts fondamentaux : Collections, requêtes live et mutations optimistes

Collections : la fondation de vos données

Les collections sont des ensembles typés d’objets qui peuvent être alimentés depuis n’importe quelle source—APIs REST, GraphQL ou moteurs de synchronisation comme ElectricSQL. Elles encapsulent vos appels useQuery existants :

const todoCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => api.todos.getAll(),
    getKey: (item) => item.id,
    schema: todoSchema
  })
)

Cela semble familier car cela s’appuie sur les patterns de TanStack Query. La différence ? Les collections normalisent vos données et permettent des requêtes réactives à travers les relations.

Requêtes live : réactivité sans code répétitif

Les requêtes live se mettent à jour automatiquement lorsque les données sous-jacentes changent—sans invalidation manuelle du cache, sans chaînes de useMemo :

const { data: activeTodos } = useLiveQuery((query) =>
  query
    .from({ todos: todoCollection })
    .where(({ todos }) => eq(todos.completed, false))
)

Lorsque le statut d’une tâche change, cette requête se met à jour en moins de 1 ms. Le moteur de flux de données différentiel garantit que seules les lignes affectées sont recalculées, pas l’ensemble du dataset.

Mutations optimistes : mises à jour instantanées de l’interface

TanStack DB gère automatiquement les mises à jour optimistes, avec annulation intégrée en cas d’échec :

// Avant : Mises à jour optimistes manuelles avec TanStack Query
const mutation = useMutation({
  mutationFn: createTodo,
  onMutate: async (newTodo) => {
    // Plus de 20 lignes de code répétitif...
  }
})

// Après : TanStack DB
todoCollection.insert({
  id: uuid(),
  text: 'Ship faster',
  completed: false
})

La mutation apparaît instantanément dans votre interface et s’annule automatiquement si le serveur la rejette. Pas de code répétitif, pas de gestion manuelle de l’état.

Pourquoi le flux de données différentiel change tout

La gestion d’état traditionnelle impose un compromis : soit effectuer de nombreux appels API (réseau lent), soit filtrer de larges ensembles de données côté client (rendu lent). Le flux de données différentiel offre une troisième option : charger les données normalisées une fois, puis effectuer des jointures incrémentales ultra-rapides dans le navigateur.

Des entreprises comme Linear et Figma obtiennent leurs interfaces instantanées grâce à des systèmes de mise à jour différentielle développés sur mesure. TanStack DB démocratise cette approche, rendant la réactivité en quelques fractions de milliseconde accessible à toute application JavaScript.

Synchronisation local-first avec ElectricSQL

Bien que TanStack DB fonctionne parfaitement avec REST et GraphQL, il brille vraiment lorsqu’il est associé à des moteurs de synchronisation. ElectricSQL, par exemple, utilise la réplication logique Postgres pour diffuser les changements directement aux clients :

const todoCollection = createCollection(
  electricCollectionOptions({
    shapeOptions: {
      url: 'http://localhost:3003/v1/shape',
      params: { table: 'todos' }
    },
    getKey: (item) => item.id
  })
)

Désormais, tout changement dans votre base de données Postgres met instantanément à jour tous les clients connectés—sans plomberie WebSocket, sans diffusion manuelle. Ce pattern de synchronisation local-first élimine complètement la latence réseau des interactions utilisateur.

Parcours d’adoption progressive

TanStack DB se superpose à votre configuration TanStack Query existante. Commencez avec une collection, conservez vos appels API actuels et migrez progressivement :

1. Encapsulez une requête existante dans une collection
2. Remplacez les tableaux filtrés par des requêtes live
3. Simplifiez les mutations avec des mises à jour optimistes automatiques
4. (Optionnel) Ajoutez la synchronisation temps réel avec ElectricSQL

Chaque étape améliore les performances et réduit la complexité. Aucune réécriture complète n’est nécessaire.

Conclusion

TanStack DB apporte le flux de données différentiel à JavaScript, permettant des interfaces réactives qui se mettent à jour en microsecondes plutôt qu’en millisecondes. En étendant TanStack Query avec des collections et des requêtes live, il élimine les compromis traditionnels entre efficacité réseau et performance de rendu.

Bien qu’encore en version bêta, TanStack DB est prêt pour l’exploration et l’adoption progressive. Commencez avec une seule collection dans une fonctionnalité non critique et constatez la différence que font les mises à jour en quelques fractions de milliseconde sur la fluidité de votre application. Vos utilisateurs—et votre code—vous en remercieront.

FAQ

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.