TanStack Start v1 est entré en Release Candidate au printemps 2026 et apporte enfin une réponse moderne, type-safe et basée sur Vite à la question du rendu côté serveur React, sans la lourdeur de Next.js et sans la magie cachée de Remix. Pour une équipe qui démarre une application à Dakar ou Abidjan, c’est aujourd’hui un excellent point d’entrée : la pile reste open source, le bundler est Vite 6, et le routeur est strictement typé du backend jusqu’au composant. Ce tutoriel s’adresse à un développeur qui connaît React mais qui n’a jamais touché à TanStack Router ou TanStack Start. Vous allez installer le starter officiel, comprendre l’arborescence générée, écrire votre première route, lancer le serveur de développement, vérifier le rendu HTML avec curl, puis produire un build de production. À la fin, vous aurez un projet propre, prêt à recevoir vos vraies routes métier.

Cet article s’inscrit dans la série autour de TanStack Start en production 2026 qui sert de carte d’orientation pour l’écosystème.

Prérequis

Node.js 20.19+ ou Node 22 LTS recommandé en 2026 (vérifiez avec node -v)
npm 10+, pnpm 9+ ou bun 1.1+ au choix
Éditeur avec support TypeScript natif (VS Code, Cursor, WebStorm)
Navigateur moderne pour tester le rendu
Niveau attendu : à l’aise avec React, JSX, npm scripts, ligne de commande
Temps estimé : 35 à 50 minutes pour aller jusqu’au build de production
Connaissance utile : notions de SSR et de file-based routing, mais le tutoriel reprend les bases

Étape 1 — Vérifier l’environnement Node et le gestionnaire de paquets

Avant de toucher à TanStack Start, on s’assure que Node est suffisamment récent. La RC de TanStack Start exige Node 20.19 minimum à cause de modules ESM utilisés par Vite 7 et par la couche serveur. Sur une machine de développement à Lomé ou ailleurs, beaucoup d’environnements traînent encore en Node 18 hérité d’un précédent projet, ce qui produit des erreurs cryptiques au premier npm run dev. On vérifie également npm pour éviter des soucis de résolution de dépendances peer.

node -v
npm -v
# si Node < 20.19, mettre à jour avec nvm
nvm install 22
nvm use 22

La sortie attendue est v22.x.x (ou v20.19.x au minimum) pour Node et 10.x ou plus pour npm. Si la commande nvm n’existe pas sur votre poste, installez d’abord nvm-windows ou nvm-sh selon votre système. Une fois Node confirmé, on passe à la création du projet.

Étape 2 — Créer le projet avec la CLI officielle TanStack

La méthode recommandée par l’équipe TanStack en 2026 est la CLI create-tanstack, qui scaffolde un projet TanStack Start complet avec les bonnes versions verrouillées et pose les bonnes questions sur le bundler, le router mode et l’inclusion de TanStack Query. C’est plus fiable que de partir d’un template Git aléatoire qui peut être désynchronisé. On crée le projet dans un dossier vide nommé boutique-app à titre d’exemple.

npm create tanstack@latest boutique-app

L’outil pose ensuite quelques questions interactives. Sélectionnez React comme framework, Start comme type de projet (et non pas Router seul), TypeScript activé, Vite comme bundler, et acceptez l’inclusion de TanStack Query si on vous la propose. Le scaffolder génère le dossier en quelques secondes, télécharge les dépendances et imprime un récapitulatif. À ce stade le projet n’est pas encore lancé mais il est prêt.

Étape 3 — Lire et comprendre la structure générée

Avant d’écrire la moindre ligne, on prend cinq minutes pour comprendre ce que la CLI a posé sur le disque. C’est la base sur laquelle vous construirez tout le reste. La structure suit la convention file-based routing — chaque fichier dans src/routes devient une route HTTP, et un fichier généré routeTree.gen.ts centralise l’arbre typé pour le compilateur. Cette génération est automatique grâce au plugin Vite installé par défaut.

boutique-app/
├── src/
│   ├── routes/
│   │   ├── __root.tsx        # Layout racine de l'app
│   │   └── index.tsx         # Route /
│   ├── router.tsx            # Création de l'instance de router
│   ├── routeTree.gen.ts      # Généré, ne pas éditer
│   ├── client.tsx            # Entrée client (hydratation)
│   └── ssr.tsx               # Entrée serveur (handler)
├── public/
├── vite.config.ts
├── tsconfig.json
├── package.json
└── app.config.ts             # Optionnel selon version

La règle d’or : vous écrivez vos routes dans src/routes, vous ne touchez jamais à routeTree.gen.ts. Le plugin Vite régénère ce fichier à chaque sauvegarde. Si vous le modifiez à la main, vos changements seront écrasés au prochain démarrage. La séparation client.tsx et ssr.tsx est ce qui distingue Start d’un simple Router côté client.

Étape 4 — Inspecter package.json et vite.config.ts

Le contenu exact des fichiers de config dépend de la version installée, mais en mai 2026 vous obtiendrez quelque chose proche de ce qui suit. On regarde d’abord package.json pour repérer les scripts npm fournis et les versions des paquets clés. Les trois paquets centraux sont @tanstack/react-start, @tanstack/react-router et le plugin de génération de routes @tanstack/router-plugin.

{
  "name": "boutique-app",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite dev --port 3000",
    "build": "vite build",
    "start": "node .output/server/index.mjs"
  },
  "dependencies": {
    "@tanstack/react-router": "^1.169.0",
    "@tanstack/react-start": "^1.167.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@tanstack/router-plugin": "^1.167.0",
    "@vitejs/plugin-react": "^4.3.0",
    "@tanstack/react-router-devtools": "^1.169.0",
    "typescript": "^5.6.0",
    "vite": "^7.0.0"
  }
}

Trois scripts vous suffisent pour 95 % du quotidien : dev lance le serveur Vite en mode HMR sur le port 3000, build produit un dossier .output portable, et start exécute le serveur de production. On regarde maintenant la config Vite, où le plugin TanStack Start s’enregistre.

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { tanstackRouter } from '@tanstack/router-plugin/vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'

export default defineConfig({
  plugins: [
    tanstackRouter({ target: 'react', autoCodeSplitting: true }),
    tanstackStart(),
    react(),
  ],
})

L’ordre des plugins compte. tanstackRouter doit s’enregistrer avant react() sinon la génération de l’arbre de routes peut manquer des fichiers transformés. Le plugin tanstackStart() ajoute la couche serveur (SSR, server functions). Le flag autoCodeSplitting: true active le découpage automatique de chaque route en chunk, utile pour des connexions plus lentes à Cotonou ou Bamako.

Étape 5 — Écrire la route racine __root.tsx

Le fichier src/routes/__root.tsx est le layout commun à toutes les routes : c’est ici qu’on déclare la balise html, le head, et un Outlet qui sert de point d’insertion pour les routes filles. C’est différent d’une simple App.tsx React classique : la racine est elle-même typée comme une route et reçoit ses propres metadata. Voici une version minimaliste mais correcte.

// src/routes/__root.tsx
import { createRootRoute, Outlet, HeadContent, Scripts } from '@tanstack/react-router'

export const Route = createRootRoute({
  head: () => ({
    meta: [
      { charSet: 'utf-8' },
      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
      { title: 'Boutique App' },
    ],
  }),
  component: RootComponent,
})

function RootComponent() {
  return (
    <html lang="fr">
      <head>
        <HeadContent />
      </head>
      <body>
        <Outlet />
        <Scripts />
      </body>
    </html>
  )
}

Trois éléments à retenir. HeadContent rend le titre et les meta déclarés dans head() de chaque route. Scripts injecte les scripts d’hydratation. Outlet est le slot où les routes filles s’affichent. Sans Scripts, le HTML serait servi mais aucune interactivité React ne démarrerait côté client.

Étape 6 — Créer la première route index.tsx

On a maintenant un layout racine, mais aucune page concrète à afficher sur /. On corrige ça avec un fichier src/routes/index.tsx. La convention est claire : index.tsx mappe vers la racine de la route parente, donc ici la racine du site. La route est créée via createFileRoute qui prend le chemin sous forme de chaîne typée — le plugin Vite vérifiera que ce chemin correspond bien au nom du fichier.

// src/routes/index.tsx
import { createFileRoute } from '@tanstack/react-router'

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

function HomePage() {
  return (
    <main style={{ padding: '2rem', fontFamily: 'system-ui' }}>
      <h1>Bonjour depuis TanStack Start</h1>
      <p>Premier rendu SSR fonctionnel.</p>
    </main>
  )
}

On garde le composant volontairement frugal. Si vous ouvrez routeTree.gen.ts après cette sauvegarde (juste pour curiosité), vous verrez une nouvelle entrée pour indexRoute automatiquement ajoutée. C’est le plugin qui a fait le travail en arrière-plan dès la sauvegarde. Si vous ne voyez rien apparaître, c’est probablement que le serveur dev n’est pas encore lancé — c’est l’étape suivante.

Étape 7 — Lancer le serveur de développement

Avec les deux fichiers de route en place, on peut enfin lancer la commande de développement. Ouvrez un terminal à la racine du projet et exécutez la commande ci-dessous. Le serveur s’attache au port 3000 par défaut, conformément au script dev du package.json. Si ce port est déjà occupé par une autre application sur votre machine, Vite fallback automatiquement sur le port suivant disponible.

npm run dev

La sortie attendue ressemble à ceci, avec une URL cliquable et le mode SSR confirmé. Le démarrage prend quelques secondes la première fois car Vite pré-bundle les dépendances. À partir de la seconde exécution, le démarrage tombe sous la seconde grâce au cache node_modules/.vite.

  VITE v7.0.x  ready in 842 ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Ouvrez l’URL dans votre navigateur. Vous devez voir le titre Bonjour depuis TanStack Start et le sous-titre. C’est la confirmation que le routeur, le SSR et l’hydratation fonctionnent. Si la page est blanche, ouvrez la console pour repérer une erreur — neuf fois sur dix, c’est un import manquant dans __root.tsx ou un typo dans le chemin de createFileRoute.

Étape 8 — Vérifier le rendu serveur avec curl

Il ne suffit pas que la page s’affiche dans le navigateur — il faut aussi vérifier que le HTML est bien rendu côté serveur, c’est tout l’intérêt de Start par rapport à un SPA Vite classique. La méthode la plus simple est curl qui ne sait pas exécuter JavaScript. Si le HTML envoyé contient déjà votre titre, le SSR fonctionne. Sinon, vous recevriez un shell vide avec uniquement la balise root et un script.

curl -s http://localhost:3000/ | head -40

Vous devez voir dans la sortie une ligne contenant <h1>Bonjour depuis TanStack Start</h1>. C’est la preuve formelle que le serveur a rendu le composant en HTML avant de l’envoyer au client. Côté navigateur, le bundle hydrate ensuite ce HTML pour le rendre interactif. Cette double exécution serveur puis client est le cœur de Start.

Étape 9 — Produire un build de production

Le mode dev est confortable mais pas représentatif de la performance réelle. Pour préparer un déploiement, on lance le script build qui génère un dossier .output autonome contenant le serveur Node, les assets statiques et les chunks JavaScript optimisés. Ce dossier peut être copié sur n’importe quel hébergeur Node (un VPS, un conteneur, un service comme Fly.io ou Render).

npm run build
ls .output/
# server/  public/  nitro.json

Le dossier .output/server contient l’entrée Node index.mjs, le dossier .output/public reçoit les assets immuables servis directement par votre CDN. Pour exécuter le serveur de production en local et vérifier qu’il démarre, utilisez la commande ci-dessous. C’est exactement ce que ferait votre Dockerfile en CMD.

node .output/server/index.mjs
# Listening on http://0.0.0.0:3000

Refaites un curl http://localhost:3000/ dans un autre terminal pour confirmer que le HTML SSR est toujours présent en mode build. Si tout fonctionne en dev mais casse en build, c’est en général un import dynamique qui charge un module Node-only côté client — TanStack Start vous le signalera explicitement dans le log de build.

Étape 10 — Aller plus loin avec Query et le file-based routing

Vous avez maintenant un projet TanStack Start v1 fonctionnel, vérifié en SSR, et capable de produire un build de production. La suite logique consiste à ajouter de vraies routes, à plugger TanStack Query pour la gestion du cache de données, et à structurer vos layouts imbriqués. Pour le routage avancé (paramètres dynamiques, layouts groupés, search params typés), la lecture du tutoriel sur le file-based routing avec TanStack Router est l’étape directe à suivre.

Pour la couche données et la gestion du cache côté serveur, le tutoriel sur Query SSR et l’hydratation explique comment précharger des requêtes côté serveur et hydrater le cache côté client. Et si votre projet est encore au stade de comparaison d’architecture frontend, l’aperçu React frontend pour PME donne une grille de lecture sur le choix d’un stack React 2026.

Erreurs fréquentes

Erreur	Cause probable	Solution
`Cannot find module '@tanstack/react-start'`	Installation incomplète, lock file divergent	Supprimer `node_modules` et `package-lock.json`, relancer `npm install`
`SyntaxError: Unexpected token '?'`	Node trop ancien (< 20.19)	Mettre Node à jour avec nvm puis recréer le projet
Page blanche, console vide	`Scripts` oublié dans `__root.tsx`	Importer et placer `<Scripts />` en fin de `<body>`
`routeTree.gen.ts` non généré	Plugin `tanstackRouter` mal positionné	Le placer avant `react()` dans `vite.config.ts`
HMR ne recharge pas les routes	Fichier hors de `src/routes`	Vérifier le chemin et l’option `routesDirectory` du plugin
Build ok mais 404 en prod	Mauvaise base URL ou reverse proxy mal configuré	Définir `base` dans `vite.config.ts` et ajuster le reverse proxy

FAQ

Quelle est la différence entre TanStack Router et TanStack Start ?

TanStack Router est uniquement le routeur côté client (avec un mode SSR optionnel). TanStack Start est le framework complet qui ajoute le serveur Vite, le rendu SSR, les server functions et la couche de build. Si votre app est un SPA pur, Router suffit. Pour du SSR, Start est requis.

Faut-il React 19 obligatoirement ?

TanStack Start v1 cible React 19 par défaut en 2026 et profite des nouvelles API serveur. Sur React 18.3 le projet peut démarrer mais certaines fonctionnalités (Suspense streaming amélioré, hooks serveur) ne seront pas disponibles. Mieux vaut rester sur React 19.

Peut-on utiliser pnpm ou bun à la place de npm ?

Oui, les trois sont supportés. Lancez la CLI avec pnpm create tanstack@latest ou bun create tanstack@latest. Bun donne un démarrage plus rapide en local mais certains plugins Vite restent moins éprouvés en CI sur Bun, à tester selon votre pipeline.

Comment déployer un build TanStack Start ?

Le dossier .output est un livrable Nitro standard. Vous pouvez le déployer sur un VPS classique avec PM2, dans un conteneur Docker minimal, ou sur des plateformes comme Fly.io, Render, Railway, Cloudflare Workers (selon le preset Nitro choisi). En 2026 le preset Node est le plus stable.

TanStack Start est-il prêt pour la production en 2026 ?

Le projet est officiellement en Release Candidate au printemps 2026, l’API est considérée stable par l’équipe et les versions sont publiées presque quotidiennement. De nombreuses équipes l’utilisent déjà en production, mais sur un projet critique on lit toujours le changelog avant un upgrade mineur.

Setup TanStack Start v1 — installation et premier rendu en 2026