Publier React avec Vite et éviter le 404 au rechargement

Un site React accessible sur localhost dépend encore de votre ordinateur. Si Vite produit des fichiers statiques et que l’application ne nécessite pas son propre serveur, vous pouvez construire ces fichiers et les publier depuis Git. Le serveur de développement peut ensuite être arrêté.

Ce parcours utilise un exemple original React et Vite sous licence MIT. La démonstration publiée propose deux routes : l’accueil et /about. Elle comprend une image originale, du CSS et une variable publique de construction. Elle n’implémente ni authentification, ni paiement, ni API, ni base de données.

Si votre projet utilise Astro et Markdown, consultez le guide de publication statique depuis Git, avec des routes et des URL canonical vérifiées sur une démonstration publiée.

Si l’interface React s’affiche mais que ses requêtes API échouent après la publication, suivez le diagnostic frontend et API en production.

Vérifiez ce que votre outil d’IA a produit

Repérez package.json et lisez ses scripts. Dans cet exemple, build exécute Vite et crée dist. React ne détermine pas à lui seul le type d’hébergement : une interface qui appelle Supabase, une API ou un serveur dépend aussi de ces services et de leurs identifiants correctement configurés.

Ne supprimez pas les dépendances backend pour faire passer une application pour statique. Consultez quel hébergement choisir pour un site créé avec une IA pour distinguer ce qui s’exécute dans le navigateur de ce qui nécessite un serveur. Cette recette ne démontre pas non plus la prise en charge du rendu serveur de Next.js.

Préparez un dépôt reproductible

Copiez l’exemple ou créez un fork dans votre compte GitHub, en conservant sa licence. Incluez package.json, package-lock.json, index.html, src, public et la configuration Vite. Le fichier de verrouillage permet à npm ci d’installer les versions enregistrées ; il ne met pas automatiquement les dépendances à jour.

L’exemple nécessite Node 22.19.0 ou une version ultérieure. Construisez-le d’abord sur votre ordinateur :

npm ci
npm run build

Vérifiez la présence de dist/index.html et des fichiers CSS et JavaScript dans dist/assets. npm run dev et npm run preview sont des outils locaux de développement et de vérification, pas le processus de production de cette publication statique.

Configurez Projects pour cet exemple

Connectez votre fournisseur Git et sélectionnez le dépôt en suivant la documentation de Projects. Vérifiez les autorisations avant de les accorder. Voici les paramètres testés :

Ces valeurs correspondent à ce dépôt. Un monorepo, un autre script ou un dossier de sortie personnalisé nécessite sa propre configuration. Ne publiez ni node_modules ni votre dossier personnel.

Évitez le 404 lors de l’ouverture directe d’une route

Depuis l’accueil, React peut modifier l’URL en /about sans demander un autre fichier HTML. Au rechargement, le navigateur demande /about à l’hébergement. Si ce fichier n’existe pas et qu’aucun fallback n’est prévu, la requête retourne 404 même si le lien fonctionnait auparavant.

Sur Hostbrid, cet exemple active le fallback avec le fichier public/.hostbrid-spa. Vite le copie à la racine de dist. Pour un site contenant ce marqueur et un fichier d’index, l’hébergement sert index.html pour les routes de navigateur. Les sites sans marqueur conservent leur comportement habituel. Le marqueur n’est pas accessible par HTTP et les fichiers de ressources absents continuent de retourner 404.

Vérifiez que l’export conserve les fichiers dont le nom commence par un point. Créer le marqueur dans un dossier que le build ne copie pas ne suffit pas. Une route inconnue peut retourner le HTML avec un statut 200 et afficher « Page non trouvée » dans React : cela n’en fait pas une page valide pour le SEO. Définissez les routes réelles et vérifiez le rendu et l’indexation avant de publier de nombreuses URL.

Écran blanc : identifiez la requête en échec

Ouvrez les outils du navigateur, sélectionnez Network, rechargez et examinez la requête en échec. Vérifiez son URL, son statut, son type de contenu et sa réponse. Une page d’accueil qui renvoie 200 ne prouve pas que le JavaScript est chargé.

• Le document /about renvoie 404 : vérifiez le marqueur et le fallback décrits plus haut.
• Le JavaScript ou le CSS renvoie 404 : comparez l’URL demandée aux fichiers construits. Publiez le dossier dist complet et vérifiez que le HTML et les ressources proviennent de la même construction.
• Le JavaScript renvoie 200 avec du HTML : le serveur fournit une page, éventuellement l’index ou une erreur, là où le navigateur attend du code. Rediriger toutes les requêtes vers index.html ne résout pas cela ; les ressources absentes doivent toujours renvoyer 404.
• Les fichiers sont chargés, mais l’écran reste blanc : consultez la console. Une erreur de l’application, une API externe ou une variable absente exige un autre diagnostic que le fallback.

Notre exemple est publié à la racine de son sous-domaine. Pour préparer une installation sous /demo/ sur un autre serveur, l’option base de Vite adapte les chemins des ressources lors de la construction ; configurez séparément le préfixe du routeur. base: './' ne corrige pas toutes les erreurs de rechargement des routes profondes. Ce guide ne démontre pas que Projects permet une publication sous n’importe quel préfixe.

Vous pouvez aussi utiliser notre diagnostic statique original sous licence MIT. Avec Node 22.23.3, téléchargez la version testée et lancez :

git clone https://github.com/ocentelles/hostbrid-static-diagnostics.git
cd hostbrid-static-diagnostics
git checkout 203e71e33e9864f8048dccee3d886fa3c87dcb1c
node --version
node diagnose.mjs https://hostbrid-react-demo.hostbrid.dev/

Remplacez l’URL de la démo par celle de votre site public. Aucune installation de dépendances n’est nécessaire. L’outil vérifie le HTML et les références directes JavaScript/CSS de la même origine ; il n’exécute pas React et ne vérifie pas les images, les API ou les routes internes. Il renvoie du JSON et un code de sortie non nul en cas d’échec ou de vérification incomplète. La démo de la commande a passé trois requêtes GET ; l’outil dispose de 28 tests HTTP locaux. Un résultat correct ne remplace pas les tests dans le navigateur.

Nous avons aussi publié l’exemple original de routes et de ressources : six cas locaux, dont des bases incorrectes, le préfixe du routeur et du HTML servi comme JavaScript. Son README explique leur reproduction avec Node et Chrome ; cet essai n’ajoute aucune capacité commerciale à Projects.

Définissez les variables sans publier de secrets

L’exemple utilise VITE_CONTACT_LABEL, un libellé incorporé au JavaScript pendant la construction. Les variables VITE_* sont publiques : n’y placez jamais de mots de passe, de clés privées ou de jetons d’administration. Modifier la variable nécessite un nouveau build ; les fichiers déjà publiés ne changent pas.

Vérifiez pourquoi l’ancienne valeur apparaît encore

Dans notre expérience originale sur les variables de Vite, nous avons construit un libellé avec la valeur A, puis servi les mêmes fichiers depuis un processus utilisant la valeur B. Le navigateur affichait toujours A après rechargement, et le hash du JavaScript restait identique. Une nouvelle construction avec B a changé le libellé et le hash. Sans la variable, le texte de remplacement prévu est apparu.

Si vous voyez une ancienne valeur, vérifiez la variable reçue par le processus de construction et le build que vous publiez. Modifier uniquement l’environnement du serveur qui fournit les fichiers statiques ne réécrit pas le bundle. Cette expérience locale vérifie une configuration statique de Vite ; elle ne démontre ni la transmission des variables par le panneau Hostbrid, ni le comportement du SSR ou d’une configuration chargée à l’exécution.

Vous pouvez reproduire les trois constructions avec Node 22.23.3 et Chrome sur macOS en suivant le README du dépôt. Utilisez des valeurs d’exemple publiques : vérifier un seul marqueur sans préfixe dans cette expérience ne constitue pas un audit des secrets de votre projet.

Si le navigateur appelle encore localhost

Rechargez le site publié dans Network et examinez la requête qui échoue. Une URL comme http://localhost:3000/api/contact demande au navigateur du visiteur de contacter son propre ordinateur. Publier les fichiers React ne publie pas automatiquement ce serveur.

Repérez où cette URL est construite : code, configuration ou variable publique de compilation. Remplacez-la par le point d’accès HTTPS d’un backend réellement déployé. Avec une variable VITE_, reconstruisez et republiez : modifier une variable ensuite ne change pas le JavaScript déjà généré. N’y placez jamais d’identifiants privés.

Une référence relative /api/contact évite de fixer le nom d’hôte, mais demande cette route à l’origine qui sert le site. Utilisez-la uniquement si le backend ou un proxy configuré y existe. Un 404 ou le HTML de la page d’accueil indique que la route doit encore être examinée ; cela ne prouve pas un envoi réussi.

Ne remplacez pas toutes les occurrences de 0.0.0.0 : cette adresse peut être correcte pour l’écoute d’un serveur. L’URL demandée par le navigateur doit viser la destination publique. Rechargez puis vérifiez URL, réponse et action attendue. Corriger le nom d’hôte ne vérifie pas à lui seul CORS, connexion ou réception d’un formulaire.

Vérifiez le site publié

Ouvrez l’adresse HTTPS depuis un autre appareil. Visitez l’accueil, saisissez /about directement et rechargez la page. Vérifiez l’image, les styles et le contenu de la deuxième route. Une demande de fichier JavaScript inexistant doit retourner 404, pas du HTML avec un statut 200.

Test du 8 octobre 2026 : nous avons publié le commit db329ae via le processus de construction de Projects. L’accueil et /about retournent 200 ; CSS et JavaScript sont servis avec les types de contenu appropriés. Chrome a exécuté React sur /about et affiché le libellé public du build. Les ressources absentes et le marqueur ont retourné 404. La configuration des routes a été testée sur les deux réplicas d’hébergement, y compris pour les sites qui n’activent pas le fallback.

Ce test utilise un projet propre à Hostbrid. Il vérifie la construction et la publication, mais pas l’inscription d’un client, son autorisation OAuth ni les déploiements automatiques à chaque push. Consultez Projects et les offres actuelles pour choisir la capacité. Si votre site nécessite un backend, choisissez où l’exécuter et testez-le avant de proposer l’application à vos utilisateurs.

Consultez aussi la documentation de construction de Vite et ses variables d’environnement publiques.

Si votre dépôt contient deux applications et un paquet partagé, consultez le diagnostic npm workspaces avant de retirer des dossiers : la racine d’installation et la sortie publiée ont des rôles différents.