Comment déployer React + Vite sur Cloudflare Pages

Préparer le projet Vite

Commencez par une application React + Vite qui s’installe et se construit correctement sur une machine propre. Validez le fichier de verrouillage des dépendances afin que Cloudflare installe les mêmes versions que votre environnement local. Lorsque le projet dépend d’une version précise de Node.js, indiquez-la explicitement pour éviter les différences entre les postes de développement et l’environnement de construction.

Vérifiez que package.json contient une commande de production, généralement vite build ou une vérification TypeScript suivie de vite build. Par défaut, Vite écrit l’application déployable dans le dossier dist. Éliminez les chemins de fichiers locaux, les adresses d’API réservées au développement et les références d’assets qui ne fonctionnent que depuis le serveur local.

Avant de connecter le dépôt, exécutez npm ci puis npm run build et examinez le contenu de dist. Cette étape détecte les erreurs TypeScript, les différences de majuscules dans les noms de fichiers, les médias manquants et les hypothèses de chemin qui échoueraient uniquement sur l’infrastructure de déploiement.

Configurer Cloudflare Pages

Créez un projet Pages dans le tableau de bord Cloudflare et connectez le fournisseur Git qui héberge l’application. Sélectionnez volontairement la branche de production. Le préréglage Vite propose normalement npm run build comme commande et dist comme dossier de sortie, mais contrôlez ces deux valeurs avant le premier déploiement.

Cloudflare crée une URL de prévisualisation isolée pour les branches non productives et les demandes de fusion. Utilisez ces versions comme candidates à la mise en ligne : testez l’application compilée avant de fusionner. Elles permettent également de vérifier les redirections, les en-têtes, les aperçus sociaux et les intégrations propres à chaque environnement.

Conservez autant que possible le comportement du déploiement dans le dépôt. Les fichiers robots.txt, 404.html, les règles de redirection, les en-têtes et le sitemap généré peuvent ainsi être relus et rester identiques entre les environnements. Les règles uniquement configurées dans un tableau de bord sont plus difficiles à retrouver et à reproduire.

Gérer les variables d’environnement en sécurité

Ajoutez la configuration publique nécessaire à la construction dans les paramètres du projet Pages et utilisez des valeurs distinctes pour la prévisualisation et la production lorsque cela est nécessaire. Vite expose au navigateur uniquement les variables préfixées par VITE_. Ce préfixe détermine leur visibilité, mais ne les rend pas secrètes : toutes ces valeurs sont lisibles dans le JavaScript généré.

Ne placez jamais une clé d’API privée, des identifiants de base de données, un secret de signature ou un jeton de service sans restriction dans une variable VITE_. Les opérations sensibles doivent passer par un endpoint authentifié, une Cloudflare Function ou un autre backend de confiance. Une clé utilisée directement dans le navigateur doit être volontairement publique, limitée par domaine et dotée des permissions minimales.

Documentez les noms des variables requises dans un fichier d’exemple sans y inscrire de valeurs réelles. Faites échouer la construction avec un message clair lorsqu’une configuration essentielle manque, au lieu de publier une version dont le défaut ne deviendra visible qu’au moment où un visiteur utilise la fonctionnalité concernée.

Gérer les routes React Router

La navigation côté client peut masquer un problème de routage. Un clic sur un lien React Router fonctionne parce que l’application est déjà chargée, tandis que l’actualisation de cette même URL demande à Cloudflare un asset correspondant. Testez les deux scénarios. Chaque route publique doit correspondre à un fichier HTML généré ou être couverte par un fallback volontaire.

Pour les pages marketing et éditoriales, générer un fichier HTML pour chaque route importante est plus sûr que de dépendre entièrement d’une réponse SPA générique. Une sortie propre à la route permet aux moteurs de recherche, aux réseaux sociaux et aux visiteurs dont JavaScript n’est pas encore exécuté de recevoir immédiatement le bon titre, l’URL canonique, la description, les titres et le contenu.

Ajoutez un fichier 404.html à la racine lorsque les URL inconnues doivent réellement retourner un statut 404. Sans ce fichier, Cloudflare Pages peut considérer le projet comme une application monopage et servir le document racine pour les chemins inconnus. Une vraie réponse 404 empêche les URL d’articles inexistants de devenir des erreurs logicielles indexables.

Rendre les pages importantes explorables

Une application React peut mettre à jour les métadonnées après une navigation, mais le SEO de production ne devrait pas dépendre de cette mise à jour lors de la première requête. Inspectez le code source reçu, pas seulement le panneau Éléments, et confirmez que la réponse d’origine contient déjà le titre, la meta description, le lien canonique, la directive robots, le H1 principal et un contenu significatif.

Les articles doivent aussi fournir des métadonnées Open Graph et Twitter pour un partage fiable, ainsi que les données structurées Article et BreadcrumbList lorsqu’elles décrivent fidèlement la page. L’URL canonique, les liens internes, le fil d’Ariane et le sitemap doivent employer la même convention de slash afin d’éviter des redirections inutiles aux robots.

Générez les entrées du sitemap depuis la même source locale que celle utilisée pour afficher les routes. Vous évitez ainsi de publier un article sans l’ajouter aux fichiers de découverte, vous conservez des dates de modification fiables et vous empêchez les anciennes URL de rester dans le sitemap après la suppression d’un contenu.

Connecter le domaine de production

Lorsque la prévisualisation est stable, ajoutez le domaine de production depuis le projet Pages. Cloudflare indique la configuration DNS nécessaire et active le certificat. Choisissez un seul nom d’hôte canonique, par exemple le domaine racine, puis redirigez les variantes au lieu de laisser plusieurs domaines servir le même contenu.

Mettez à jour les métadonnées, les URL du sitemap, robots.txt, les listes d’autorisation d’API, les outils d’analyse et les URL de retour OAuth avec l’origine HTTPS finale. Les moteurs de recherche ne doivent jamais considérer les domaines de prévisualisation comme des alternatives canoniques au site de production.

Vérifier le déploiement de production

Ouvrez le domaine déployé dans une session privée, puis visitez et actualisez directement plusieurs routes profondes. Confirmez que la réponse réseau réussit, que les assets utilisent HTTPS et qu’une route inconnue retourne la page 404 plutôt que l’accueil. Testez les variantes avec et sans slash pour vérifier que Cloudflare redirige vers une seule forme canonique.

Inspectez le code source pour les métadonnées et les données structurées, validez sitemap.xml comme XML et vérifiez que robots.txt autorise les sections prévues tout en indiquant le sitemap de production. Chaque URL du sitemap doit fonctionner et aucune prévisualisation, expérience de laboratoire ou route inexistante ne doit être indexable.

Enfin, testez la navigation mobile, le focus clavier, les dimensions d’images et les Core Web Vitals en production. Mesurez le build déployé plutôt que le serveur Vite de développement, car la minification, le cache, les polices, les scripts tiers et le CDN influencent tous l’expérience réellement reçue par les visiteurs.

Résoudre les erreurs de déploiement courantes

Si la construction échoue, comparez le journal Cloudflare à une exécution locale propre de npm ci et npm run build. Contrôlez le dossier racine sélectionné, la version de Node, la casse des fichiers, les variables manquantes et les fichiers générés éventuellement exclus du dépôt ou de la commande de construction.

Si l’accueil fonctionne mais que les routes profondes échouent, examinez les fichiers produits dans dist et décidez si chaque route doit posséder un HTML statique ou utiliser un fallback intentionnel. Si le déploiement réussit mais affiche un ancien contenu, vérifiez d’abord que la branche de production contient réellement la modification avant d’examiner le cache.

Considérez le déploiement comme une partie de l’architecture de l’application et non comme la dernière commande du projet. Un pipeline réduit et explicite rend React + Vite sur Cloudflare Pages rapide à publier, simple à auditer et plus facile à rétablir lorsqu’un élément évolue.