TanStack AI : un SDK TypeScript pour le chat en streaming et les outils typés

Le problème visé : des appels de modèles qui restent typés d'un bout à l'autre

Le README décrit un SDK TypeScript destiné à construire des applications d'IA, avec un accent mis sur la sûreté de types et l'indépendance vis-à-vis du fournisseur. Le public visé est celui qui écrit déjà du TypeScript et veut brancher OpenAI, Anthropic, Gemini ou OpenRouter sans réécrire sa couche applicative à chaque changement de modèle. Le projet se présente comme composé d'activités composables et d'adaptateurs de fournisseurs, avec un import sélectif : on peut n'importer que le chat, puis ajouter image, audio, vidéo, synthèse vocale, transcription, résumé, temps réel, Code Mode, devtools et liaisons de framework selon les besoins. Cette granularité est la promesse centrale : le coût d'entrée se limite au paquet de base et au paquet du fournisseur choisi, par exemple @tanstack/ai et @tanstack/ai-openai. Le README liste aussi ce qui est constructible : chat en streaming avec messages typés, appels d'outils et parties de raisonnement, outils exécutables côté serveur ou client depuis un même contrat, sorties structurées, invites et réponses multimodales, et clients natifs pour React, Solid, Vue, Svelte et Preact, plus un client sans interface pour les runtimes personnalisés. À noter que le README porte une mention de lauréat d'un prix JavaScript Open Source 2026, ce qui ne dit rien de la stabilité de l'API.

Le mécanisme : un adaptateur, un flux, un contrat d'outil partagé

L'exemple de streaming du README montre une route POST qui lit le corps de la requête, appelle chat() avec un adaptateur openaiText('gpt-5.2') et les messages reçus, puis renvoie toServerSentEventsResponse(stream). Le flux est donc produit par le SDK et sérialisé en Server-Sent Events par une fonction dédiée, ce qui laisse penser que les adaptateurs de connexion mentionnés dans la documentation servent à changer ce mode de transport. Les outils suivent un autre chemin : toolDefinition() prend un nom, une description, un inputSchema et un outputSchema, puis une méthode .server() attache l'implémentation réelle. Le même contrat peut recevoir une implémentation cliente, ce qui est le point intéressant du design : la validation des entrées et sorties ne dépend pas de l'endroit où le code s'exécute. Pour les sorties structurées, chat() accepte une clé outputSchema, l'exemple du README utilisant un objet Zod avec name et age et attendant un objet typé en retour. Les schémas acceptés sont JSON Schema, Zod, ArkType, Valibot ou du JSON Schema brut. Le README mentionne également un flux d'approbation d'outils et une découverte paresseuse des outils, sans en détailler le fonctionnement dans le texte fourni.

Mise en route : les commandes et les clés telles quelles

L'installation passe par pnpm dans tous les exemples du README. Pour le socle et un fournisseur : pnpm add @tanstack/ai @tanstack/ai-openai. Pour une interface de chat React : pnpm add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-openai. OpenRouter est présenté comme un point de départ pratique pour atteindre plusieurs fournisseurs avec une seule clé : pnpm add @tanstack/ai @tanstack/ai-openrouter. Côté configuration, les clés visibles dans les extraits sont adapter, messages, outputSchema et, pour les outils, name, description, inputSchema, outputSchema. Le point d'entrée serveur est une fonction POST qui renvoie toServerSentEventsResponse(stream). Le README documente aussi une installation de compétences pour agents de codage, avec deux variantes : /plugin marketplace add TanStack/ai puis /plugin install tanstack-ai pour Claude Code et Cursor, ou npx skills add TanStack/ai -g --skill tanstack-ai tanstack-ai-migration pour tout autre agent. Dans un projet, npx @tanstack/intent@latest install relie les compétences des paquets installés à AGENTS.md et CLAUDE.md. Ces commandes supposent un agent compatible ; rien n'indique qu'elles soient nécessaires pour utiliser le SDK lui-même.

Ce que le README ne tranche pas

La section Generations est coupée dans le matériel fourni : les activités image, audio, vidéo, synthèse vocale, transcription et résumé sont annoncées, mais leurs signatures et leurs contraintes ne sont pas vérifiables ici. Il en va de même pour le mode temps réel, décrit comme reposant sur des adaptateurs de fournisseurs pour les sessions et la frappe de jetons, sans détail sur le protocole ni sur les fournisseurs réellement couverts. Le Code Mode est présenté comme un agent qui écrit et exécute du TypeScript dans un bac à sable isolé pour orchestrer des outils avec boucles, branches et appels parallèles ; le README ne précise ni la nature du bac à sable ni ses limites de ressources. Deux points méritent d'être signalés franchement. D'abord, la documentation renvoie à une page de comparaison avec le Vercel AI SDK, ce qui signifie que l'équipe assume la comparaison mais aussi qu'elle en fixe le cadre : à lire en gardant cela en tête. Ensuite, la version publiée au moment des faits est @tanstack/ai@0.53.0, et @tanstack/openai-base est passé de 0.10.9 à 0.10.10 le même jour. Une API en 0.x avec des publications rapprochées implique un coût de mise à jour réel, que le README n'aborde nulle part.

La limite concrète : le fournisseur reste une dépendance à part entière

L'indépendance vis-à-vis du fournisseur ne veut pas dire absence de dépendance au fournisseur. Le README recommande d'installer un paquet par fournisseur, par exemple @tanstack/ai-openai, et il existe un paquet séparé @tanstack/openai-base avec son propre numéro de version. Autrement dit, changer de fournisseur suppose d'ajouter un paquet et d'écrire un nouvel adaptateur, pas seulement de modifier une chaîne de caractères. Le nom du modèle est passé directement à l'adaptateur, ici openaiText('gpt-5.2'), ce qui signifie que la liste des modèles disponibles dépend du paquet installé et de sa version, pas du SDK de base. C'est un point de friction pour les projets qui veulent tester plusieurs modèles en parallèle. Par ailleurs, le SDK est spécifique à TypeScript : il n'y a pas de client Python ou Go mentionné, et une équipe dont le backend est en Java ou en Rust ne pourra en tirer qu'une partie, côté navigateur. Enfin, le README insiste sur l'import sélectif des activités, ce qui suggère que le paquet de base n'embarque pas tout ; la taille réelle d'un bundle donné n'est pas documentée dans le matériel fourni.

Face au Vercel AI SDK : la différence est dans le contrat d'outil

Le README pointe explicitement une page de comparaison avec le Vercel AI SDK, et cette comparaison est présentée comme portant sur l'architecture, la couverture fonctionnelle et les compromis. Sur la base des extraits disponibles, la différence la plus nette tient au contrat d'outil : toolDefinition() définit un schéma d'entrée et un schéma de sortie, puis attache séparément une implémentation serveur ou cliente. Le même objet décrit donc l'outil pour le modèle et pour le code qui l'exécute, dans les deux environnements. C'est un choix de conception qui impose d'écrire les schémas d'entrée et de sortie, là où d'autres approches se contentent d'un schéma d'entrée et laissent la sortie non validée. Le revers est un peu plus de code à écrire par outil. Le second axe est le découpage en paquets : activités et fournisseurs sont séparés, ce qui rend le périmètre installé explicite mais multiplie les versions à suivre. La documentation de comparaison est écrite par l'équipe du projet, donc elle décrit ce qu'elle considère comme les compromis pertinents ; c'est une lecture utile, pas un arbitrage neutre.

Coût de maintenance et licence

Le projet est publié sous licence MIT, ce qui autorise l'usage commercial, la modification et la redistribution avec conservation de l'avis de licence. Le README ne mentionne aucune clause additionnelle, aucune licence de type Commons Clause ni restriction d'usage. Pour un projet en entreprise, cela signifie que l'intégration dans un produit fermé ne pose pas de question de licence au niveau du SDK lui-même, mais les paquets de fournisseurs et les modèles appelés ont leurs propres conditions, qui ne relèvent pas de cette licence. Sur la maintenance, les faits disponibles sont limités : la branche par défaut est main, le dépôt n'est pas archivé, et la dernière poussée enregistrée date du 9 septembre 2026. Les publications récentes montrent un rythme serré, avec deux versions de @tanstack/openai-base le 3 septembre 2026 et une version de @tanstack/ai le même jour. Ce rythme est cohérent avec un projet actif, mais aussi avec une API qui bouge. Prévoir une étape de vérification des notes de version avant chaque montée de version majeure est raisonnable, sans que le README propose d'outil de migration dédié autre que la compétence tanstack-ai-migration mentionnée pour les agents.

Conclusion éditoriale

TanStack AI convient aux équipes déjà engagées sur TypeScript et un framework du périmètre annoncé (React, Solid, Vue, Svelte, Preact), qui veulent des outils partagés entre serveur et client et une porte de sortie vers plusieurs fournisseurs. Il ne convient pas à qui cherche un socle stable : la version publiée est 0.53.0 et les correctifs de @tanstack/openai-base se succèdent dans la même journée. Avant d'adopter, vérifiez le contenu réel de la page de comparaison avec le Vercel AI SDK, l'état de la section Generations dans le README, et si le paquet de votre fournisseur expose bien le modèle visé.

Sources officielles

1. License: MIT
2. Project website
3. README
4. Releases
5. TanStack/ai on GitHub