TanStack Start : un framework full-stack fondé sur un écosystème puissant

TanStack Start s'inscrit dans la lignée des frameworks modernes comme Next.js, Remix ou SvelteKit. Construit autour de la Developer Experience (DX), il exploite un écosystème riche et mature, hérité des bibliothèques populaires de TanStack, pour offrir des fonctionnalités modernes comme les Server Functions. Son approche client-first combinée au typage extrême, aux Server Functions et à un routing 100 % typesafe rend le développement fluide et sûr : on progresse vite, sans erreurs inattendues.

TanStack : un écosystème riche et mature

Pour comprendre TanStack Start, il faut d’abord explorer l’univers de TanStack. C'est une suite de bibliothèques TypeScript Open Source initiée par Tanner Linsley (créateur de Nozzle.io). Le projet est porté uniquement par son fondateur, sans investisseurs ni entreprise influençant la roadmap. Le développement est assuré par une équipe de mainteneurs reconnus, soutenus par une communauté dynamique d’utilisateurs et de contributeurs.

Les bibliothèques TanStack sont conçues pour pouvoir s'intégrer dans n'importe quelle application de la manière la plus simple possible. Elles sont :

Framework agnostique : elles peuvent fonctionner dans n'importe quel framework.
Headless : leur utilisation n'impacte pas la partie graphique et le markup des sites web.
Typesafe : leur typage TypeScript est très fort, ce qui rend leur comportement prévisible.

Les premières bibliothèques de TanStack, comme React Table et surtout React Query, ont marqué l’écosystème React. Si React Table a eu un succès modéré, React Query a véritablement changé la donne. Elle a simplifié la gestion des données serveur côté client avec des fonctionnalités comme le suivi d’état (fetching, success, error), le cache, la pagination ou encore le polling. Aujourd'hui, elle est utilisée par un tiers des applications React.

const { data: todos, isFetching, error, retry } = useQuery({
  queryKey: ['todos'],
  queryFn: getTodos,
  retry: 3,
});

if (isFetching) {
  return <p>Fetching...</p>;
}

if (error) {
  return (
    <div>
      <p>An error occurred, please retry</p>
      <button onClick={retry}>Retry</button>
    </div>
  );
}

return (
  <div>
    {todos.map((todo, i) => (
      <p key={i}>{todo}</p>
    ))}
  </div>
);

React Query a ensuite évolué pour devenir @tanstack/query, une bibliothèque agnostique du framework, permettant son utilisation avec Vue ou Solid. Cette évolution a permis à la communauté de croître davantage et d’apporter ces outils à d’autres projets que React. Cela a également été appliqué à d’autres outils comme @tanstack/table ou encore @tanstack/router.

TanStack Start : un framework full-stack moderne

Contrairement à d’autres frameworks, TanStack Start ne cherche pas à réinventer la roue. Il s’appuie sur un écosystème éprouvé et mature, tout en proposant des outils modernes pour simplifier le développement.

Une approche client-side first

Un aspect important qui différencie TanStack Start d'autres frameworks est son approche client-side first. De nombreux frameworks full-stack privilégient le rendu serveur par défaut pour optimiser les performances initiales et le SEO, mais cela peut complexifier les applications très interactives. Cela reste pratique pour des sites peu interactifs, mais devient vite contraignant quand le nombre de composants augmente.

Par exemple, avec Next.js, il faut déclarer manuellement les client components. À l’inverse, TanStack Start utilise le SSR (Server-Side Rendering) pour le rendu initial, puis l’application devient une SPA (Single Page Application), permettant une navigation fluide sans rechargements.

Cette approche peut augmenter la quantité de JavaScript gérée par le navigateur, mais combinée aux fonctionnalités de préchargement de TanStack Router, elle optimise la fluidité et la réactivité des pages.

Un routing entièrement typesafe et facile à prendre en main

L’une des forces de TanStack Start réside dans son système de routing. Son routing basé sur le filesystem permet de définir des routes simplement en créant des fichiers dans le dossier src/routes. Par exemple :

Un fichier /src/routes/account.tsx correspondra à la route /account.
Un fichier /src/routes/users/$userId.tsx correspondra à des routes dynamiques comme /users/john-doe ou /users/nobody.

Lorsqu’un fichier de route est créé, un template est automatiquement généré avec tout le nécessaire pour démarrer. De plus, un fichier routeTree.gen.ts est automatiquement mis à jour pour contenir toutes les informations de typage des routes. Ce système garantit un routing typesafe, permettant d'éviter les erreurs de lien.

<Link to={'/i-do-not-exist'}>Account</Link>
// ^? Type "/i-do-not-exist" is not assignable to type...

Ce typage s’étend aussi aux paramètres de recherche (search params) et aux paramètres de route, validés grâce à des outils comme Zod. Cela garantit une meilleure robustesse et réduit les erreurs au runtime.

TanStack Router gère les paramètres de recherche en json, ce qui est très pratique and il s'agit de modéliser des objets complexes dans l'url.

import { createFileRoute, Link } from '@tanstack/react-router';
import { zodValidator } from '@tanstack/zod-adapter';
import { z } from 'zod';

const searchParamsSchema = z.object({
  page: z.number().catch(1),
  limit: z.number().catch(10),
  isEditing: z.boolean().catch(false),
});

export const Route = createFileRoute('/teas/$teaId')({
  component: TeaListView,
  validateSearch: zodValidator(searchParamsSchema),
});

function TeaListView() {
  const params = Route.useSearch();
  // ^ params: { page: number; limit: number; isEditing: boolean }

  return (
    <Link
      to="/teas/$teaId"
      params={{
        newParam: '12345', // ^? newParam does not exist in type...
      }}
    >
      My link
    </Link>
  );
}

Pour initialiser les données des pages, les routes TanStack Router proposent un argument loader. Cet argument défini par le développeur retournant les informations nécessaires au chargement de la page. Là encore l'approche est client-side first donc quand le site est déjà chargé côté client, le "loader" est lui aussi exécuté côté client. À l'inverse, si la page doit être récupérée du serveur alors le loader est exécuté côté serveur quand la page est transmise au client.

export const Route = createFileRoute('/')({
  loader: async () => {
    return getTeas()
  },
  component: MyPage,
})

const MyPage = () => {
  const teas = Route.useLoaderData()
  //    ^ Tea[] 

  return (
    <div className="p-4 flex flex-col">
      {{ JSON.stringify(teas) }}
    </div>
  )
}

Tous ces comportements sont bien sûr gérés avec du cache afin d'assurer une bonne fluidité de la navigation cliente

Server Functions : une communication client-serveur simplifiée

TanStack Start propose deux modèles principaux de communication client-serveur, les Server Functions et les Server Routes.

Les Server Functions sont des fonctions TypeScript toujours exécutées côté serveur. Elles peuvent prendre des paramètres pouvant être validés manuellement ou par exemple, avec des schémas zod. À partir du type inféré par la validation et du type de retour de la fonction, elles peuvent être appelées de manière typesafe depuis le client comme le serveur. Leur design s’inspire du modèle RPC (Remote Procedure Call), rendant leur utilisation plus instinctive que les API REST classiques. Leur écriture est intuitive et ne représente pas un surcoût pour le développeur. Au contraire, la simplicité de la structure rend le code très lisible et prévisible.

Les urls des server functions ne sont pas déterminées à l'avance, il faut donc pouvoir les référencer pour pouvoir les utiliser ce qui les rend peu utilisables pour recevoir des requêtes d'autres applications. Les Server Functions peuvent être appelées aussi bien depuis le client que depuis le serveur, simplifiant ainsi le chargement des données initiales ou l’exécution d’actions nécessitant un traitement serveur.

import { createServerFn } from '@tanstack/start';
import { z } from 'zod';

const getTeasSchema = z.object({
  type: z.string(),
});

export const getTeas = createServerFn({ method: 'GET' })
 .validator((params: unknown) => {
    return getTeasSchema.parse(teaInit);
  })
  .handler(async ({ data }) => {
    return teaStorage.fetchAllTeas(data.type);
  });
  
export const Route = createFileRoute('/teas')({
  loader: async () => {
    const teas = await getTeas({ data: { type: "black_tea" } })

    return { teas }
  },
})

Les Server Routes de leur côté permettent de définir des endpoints côté serveur correspondant à des routes spécifiques de votre application. Elles sont par exemple pratiques pour gérer des soumissions de formulaire, de l'authentification ou des requêtes HTTP classiques. Cependant elles ne peuvent pas pas être appelées depuis le côté serveur. Pour les appeler, il faut utiliser un outil pour faire des requêtes HTTP comme fetch axios ou ky.

// routes/hello.tsx

export const ServerRoute = createServerFileRoute().methods({
  POST: async ({ request }) => {  
    const body = await request.json()
    return new Response(JSON.stringify({ message: `Hello, ${body.name}!` }))
  },
})

export const Route = createFileRoute('/hello')({
  component: HelloComponent,
})

function HelloComponent() {
  const [reply, setReply] = useState('')

  return (
      <button
        onClick={() => {
          fetch('/hello', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
            },
            body: JSON.stringify({ name: 'Tanner' }),
          })
            .then((res) => res.json())
            .then((data) => setReply(data.message))
        }}
      > Say Hello </button>
  )

Une architecture basée sur Vite

TanStack Start s’appuie sur Vite, un outil de build moderne et performant. Cette architecture, déjà adoptée par des frameworks comme SvelteKit, facilite son intégration dans des environnements supportant Vite. De plus, elle permet un déploiement multi-plateforme, que ce soit sur des services comme Vercel ou Netlify, ou dans des conteneurs Docker grâce au support de Node ou Bun.

Conclusion : un framework prometteur dans un écosystème solide

TanStack Start n’est pas un framework isolé. Il hérite d’un écosystème riche et mature, construit autour de bibliothèques populaires comme React Query, TanStack Router ou encore TanStack Table. Designé autour de la Developer Experience, il propose des fonctionnalités modernes comme les Server Functions, tout en s’intégrant parfaitement dans l’écosystème TypeScript.

Avec une communauté active et un support croissant d’outils tiers (Better Auth, Sentry, Supabase, etc.), TanStack Start s’impose comme un choix solide pour les développeurs cherchant à construire des applications web modernes et performantes.