Le déploiement d'une application Vite/React sur les pages GitHub est une étape passionnante, mais le processus peut parfois s'accompagner de défis inattendus, en particulier lorsqu'il s'agit de gérer des images et des ressources. Cet article de blog vous guidera tout au long du processus, du déploiement initial au dépannage des problèmes courants et à la recherche de solutions efficaces.

Que vous soyez débutant ou expérimenté, ce guide vous aidera à éviter les pièges courants et à déployer avec succès votre application Vite/React avec tous les éléments correctement rendus.

Conditions préalables

Avant de commencer, assurez-vous d'avoir les éléments suivants :

• Un projet Vite/React : ce guide suppose que vous avez configuré votre projet en utilisant Vite comme outil de construction et React comme framework.
• Référentiel GitHub : vous devez disposer d'un référentiel GitHub existant dans lequel vous pousserez votre application pour le déploiement.
• Pages GitHub activées : assurez-vous que les pages GitHub sont activées dans les paramètres de votre référentiel pour le déploiement.

Étape 1 : initialiser le déploiement du projet et des pages GitHub

Tout d'abord, assurez-vous que votre application Vite/React est correctement initialisée et fonctionne sur localhost. Vous pouvez créer un projet Vite de base comme suit :

npm create vite@latest

Installer les dépendances :

npm install

Exécutez le projet localement pour confirmer que tout fonctionne :

npm run dev

Une fois votre projet prêt, transférez-le vers votre référentiel GitHub.

Créer un vite.config.js pour les pages GitHub

GitHub Pages s'attend à ce que l'application soit servie à partir d'une URL de base spécifique, qui est généralement le nom de votre référentiel. Mettez à jour le fichier vite.config.js pour refléter ceci :

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

L'option de base garantit que l'application utilise le chemin de base correct lors du déploiement.

Étape 2 : créer et déployer le projet

Vous devrez installer le package gh-pages pour gérer le déploiement.

npm install gh-pages --save-dev

Dans votre package.json, ajoutez les scripts suivants pour automatiser le processus de déploiement :

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

Exécuter le déploiement :

npm run deploy

À ce stade, votre projet devrait être en ligne sur https://.github.io//, mais si vous êtes comme moi, vous pourriez rencontrer des problèmes l'application ne s'affiche pas correctement ou les images ne s'affichent pas.

Étape 3 : Problèmes courants et solutions

Problème 1 : page vierge après le déploiement

Après le déploiement, vous remarquerez peut-être que l'application charge une page vierge. Cela est souvent dû à des problèmes de routage. Par défaut, BrowserRouter de réagir-router-dom est utilisé, qui repose sur le routage côté serveur, mais GitHub Pages sert des fichiers statiques et ne gère pas les routes côté client.

Solution : utiliser HashRouter

Pour résoudre ce problème, passez de BrowserRouter à HashRouter dans votre fichier index.js ou main.jsx.

Remarque : Il n'est pas nécessaire que vous disposiez de l'interface utilisateur, il s'agit simplement d'une bibliothèque d'interface utilisateur pratique que j'utilise très souvent dans mes projets.

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

HashRouter utilise un symbole de hachage (#) dans l'URL pour suivre l'état de la navigation, permettant aux pages GitHub de desservir correctement différents itinéraires sans renvoyer un 404.

Problème 2 : erreur 404 lors de l'actualisation ou d'autres itinéraires

Après avoir résolu le problème de page vierge, un autre problème auquel vous pourriez être confronté est que l'application fonctionne sur la page d'accueil mais affiche une erreur 404 lors de la navigation vers d'autres itinéraires, surtout si vous accédez directement à un itinéraire comme /blogs ou /projects.

Cela se produit parce que GitHub Pages sait uniquement comment servir le fichier index.html et ne reconnaît pas les routes gérées par React Router.

Solution : gérer les erreurs 404 dans les paramètres des pages GitHub

Pour résoudre ce problème, vous devez créer un fichier 404.html dans votre dossier public/. Ce fichier garantira que GitHub Pages sert votre fichier index.html pour toutes les routes qu'il ne reconnaît pas, permettant à React Router de gérer le routage :

1. Copiez votre index.html dans un nouveau fichier nommé 404.html.
2. Placez ce fichier dans votre dossier public/.
3. Reconstruisez et redéployez le projet.

Problème 3 : les images ne se chargent pas en production

L'un des problèmes de déploiement les plus courants est le chargement incorrect des images. Bien qu'ils fonctionnent correctement sur localhost, vous remarquerez peut-être des liens d'image rompus après le déploiement sur les pages GitHub.

Par exemple, vous pouvez référencer une image comme celle-ci dans vos composants :

Problème : chemins d'image incorrects

Le problème ici est que les chemins absolus (commençant par /) ne fonctionnent pas bien lorsque l'application est déployée dans un sous-répertoire (par exemple, /your-repo-name/). GitHub Pages essaie de trouver l'image sur https://.github.io/Images/myImage.png au lieu de https://.github.io/your-repo-name/Images/myImage.png , entraînant une erreur 404.

Solution : utilisez BASE_URL

Pour résoudre ce problème, déplacez toutes vos images vers Public/Images, bien que cela soit facultatif, je vous recommande fortement de le faire. Vous ajouterez dynamiquement la BASE_URL aux chemins d'image en fonction de l'environnement :

1. Définissez une constante BASE_URL qui dépend de l'environnement :

   const BASE_URL = import.meta.env.BASE_URL;

1. Utilisez cette BASE_URL lorsque vous référencez des images :

REMARQUE : n'oubliez pas de supprimer le / devant les images, sinon vous le verrez doublé, un de la BASE_URL et un autre des /Images que vous avez oublié de supprimer.

Cela garantit que le chemin correct est utilisé à la fois en développement (localhost) et en production (pages GitHub).

Étape 4 : Déploiement final

Après avoir implémenté les correctifs pour le routage et les chemins d'image, reconstruisez et redéployez votre application :

npm run build
npm run deploy

Votre application Vite/React devrait maintenant être entièrement déployée avec toutes les images correctement rendues et toutes les routes correctement gérées.

En résumé:

1. Problèmes de routage : utilisez HashRouter pour un routage approprié dans les déploiements statiques tels que les pages GitHub.
2. Erreurs 404 sur les routes : créez un fichier 404.html pour vous assurer que les pages GitHub servent correctement votre application.
3. Images non chargées : déplacez toutes les images vers Public/Images et ajoutez dynamiquement BASE_URL à vos chemins d'actifs pour gérer à la fois les environnements de développement et de production.

Avec ces étapes, votre application Vite/React devrait être active et fonctionner correctement sur les pages GitHub. Bon codage et déploiement !