Migration d'un React SPA vers SSG : pourquoi et comment

Vous avez livré une application React rapide, fluide, soignée. Lighthouse Performance affiche 95. Et pourtant, trois semaines plus tard, Google Search Console signale des Soft 404 sur la moitié de vos routes. Vos pages produits, vos articles, vos services : indexés au compte-gouttes, parfois pas du tout. Le problème n'est pas votre code, c'est le rendu. Une SPA classique sert un HTML quasi-vide que Googlebot doit hydrater lui-même, avec un budget JavaScript limité et imprévisible.

La bonne nouvelle : passer en Static Site Generation (SSG) ne demande pas de refondre toute l'application. Sur trois projets clients migrés début 2026, j'ai gardé la même base Vite + React, en ajoutant uniquement une étape de pré-rendu route par route. Voici la méthode et les pièges.

Pourquoi Googlebot ignore votre React SPA

Une SPA livre un fichier index.html qui contient en gros <div id="root"></div> et un bundle JS. Le contenu réel est injecté côté client après hydration. Googlebot sait exécuter du JS, mais avec un budget contraint et asynchrone : la page passe d'abord par une file d'attente de rendu, parfois plusieurs jours. Si votre TTFB ou votre bundle dépasse certains seuils, Google indexe le HTML brut, donc rien. Résultat : Soft 404, snippets vides dans les résultats, partages OpenGraph cassés sur LinkedIn et iMessage.

Le SSG inverse la logique. Chaque route est pré-rendue en HTML complet au moment du build. Googlebot, Bingbot, les crawlers sociaux et les lecteurs RSS reçoivent un document immédiatement lisible, sans exécuter une ligne de JavaScript. L'hydratation côté client reste, pour conserver l'interactivité React habituelle.

Le SSG sans refondre toute l'application

Pour un projet Vite + React existant, vite-react-ssg est l'option la plus directe. On garde le routeur, les composants, les hooks, les appels Supabase. On remplace simplement le point d'entrée main.tsx par un export ViteReactSSG qui liste les routes à pré-rendre, et on remplace dans package.json le script vite build par vite-react-ssg build. Le reste du code applicatif ne bouge pas.

Au build, chaque route génère un dossier avec son index.html propre : dist/contact/index.html, dist/portfolio/z-depannage/index.html, etc. Côté Vercel, on règle cleanUrls: true dans vercel.json et on retire toute règle de rewrite SPA qui renverrait tout vers index.html, sinon le pré-rendu est masqué.

vite-react-ssg vs Next.js vs Astro : que choisir ?

vite-react-ssg est le bon choix quand la base existe déjà en Vite + React et qu'on veut juste l'étape pré-rendu. Migration en une journée sur un projet de taille moyenne, zéro refonte du code métier.

Next.js est un framework complet avec son propre routeur, ses conventions, son App Router. Excellent pour un nouveau projet, mais une migration depuis Vite implique de réécrire le routage, les layouts, les conventions de fichiers et souvent l'authentification. Plusieurs jours à plusieurs semaines selon la taille.

Astro brille sur les sites éditoriaux purs (blogs, docs, landing). Sur une application riche en interactions React, son modèle d'islands force à découper l'interface en composants isolés hydratés à la demande, ce qui complique le partage d'état global.

Checklist de validation post-migration

Trois vérifications non négociables après chaque build. Premièrement, le dossier dist/ doit contenir un index.html par route, et chaque fichier doit faire plusieurs kilo-octets, pas seulement la coquille SPA. Deuxièmement, ouvrir un de ces HTML et confirmer la présence de data-server-rendered="true" sur la racine, ainsi que des sections sémantiques pleines (main, article, section) contenant le texte réel. Troisièmement, valider via curl ou l'inspecteur Google Search Console que la version servie en production correspond bien au HTML pré-rendu.

Trois pièges récurrents. Le bug manifest-undefined de vite-react-ssg casse les pages 404 en SEO : workaround simple, créer un fichier vide public/static-loader-data-manifest-undefined.json contenant {}. La directive CSP script-src doit garder 'unsafe-inline' car l'hydration injecte des scripts inline obligatoires. Enfin, vérifier que le script build de package.json est bien vite-react-ssg build et non vite build, sinon Vercel déploie une version CSR sans s'en apercevoir.

Résultats sur 3 sites

Trois migrations livrées : Z-Dépannage et Milena Glow Up, plus un portfolio personnel. Scores Lighthouse passés de 60-70 à 95-100 sur les quatre catégories. Délai d'indexation Google divisé par cinq : de 1-4 semaines à 3-7 jours en moyenne, mesuré sur Search Console. OpenGraph fiable sur tous les partages sociaux, snippets corrects dans les résultats, plus aucun Soft 404 signalé.

Si votre projet React commence à recevoir du trafic organique et que vos métriques d'indexation stagnent, le SSG via vite-react-ssg est probablement le levier au meilleur rapport effort/impact. Quelques heures d'intégration, des gains durables sur le référencement et la performance perçue. Pour un audit ou un accompagnement migration, la page contact reste le point d'entrée le plus direct.