Déployer sur GitHub Pages

GitHub Pages est un service d'hébergement gratuit intégré à GitHub. Il permet de mettre en ligne des applications statiques directement depuis un repository, sans configuration de serveur.

Étape 1 — Configurer le base path

GitHub Pages héberge votre app sous https://username.github.io/nom-du-repo/ — pas à la racine /. Vite doit en être informé.

Modifiez vite.config.ts :

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

export default defineConfig({
  plugins: [react()],
  base: '/nom-de-votre-repo/', // ⚠️ Remplacez par le nom exact de votre repo
})

Étape 2 — Installer gh-pages et configurer les scripts

Installez le package gh-pages :

npm install --save-dev gh-pages

Ajoutez ces deux scripts dans package.json :

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

Comment ça fonctionne :

• predeploy s'exécute automatiquement avant deploy — il build le projet
• deploy pousse le contenu de dist/ sur une branche gh-pages

Étape 3 — Déployer

npm run deploy

Cette commande :

1. Build l'application (npm run build)
2. Crée ou met à jour la branche gh-pages
3. Pousse le contenu de dist/ sur cette branche

Étape 4 — Activer GitHub Pages

La première fois seulement, activez GitHub Pages dans les paramètres du repo :

1. Allez sur votre repository GitHub
2. Cliquez sur Settings
3. Dans le menu latéral, cliquez sur Pages
4. Sous Source, choisissez :
   • Branch : gh-pages
   • Folder : / (root)
5. Cliquez sur Save

Votre app sera disponible en 1-2 minutes à l'URL indiquée.

Gérer les routes React Router

Si vous utilisez React Router, les URLs directes (ex: /quiz) retournent une 404 — GitHub Pages cherche un fichier /quiz/index.html qui n'existe pas.

Solution : HashRouter

Remplacez BrowserRouter par HashRouter :

// Avant
import { BrowserRouter } from 'react-router-dom';

// Après
import { HashRouter } from 'react-router-dom';

function App() {
  return (
    <HashRouter>
      {/* Vos routes */}
    </HashRouter>
  );
}

Les URLs deviennent :

• https://username.github.io/kana-app/#/
• https://username.github.io/kana-app/#/quiz
• https://username.github.io/kana-app/#/study

Mises à jour

Pour redéployer après des modifications :

# Faites vos modifications, puis :
git add .
git commit -m "Update app"
git push origin main

# Redéployez
npm run deploy

Dépannage

Page blanche après déploiement → Vérifiez que base dans vite.config.ts correspond exactement au nom du repo.

Erreur 404 sur les routes → Passez de BrowserRouter à HashRouter (voir section ci-dessus).

npm run deploy échoue → Vérifiez que gh-pages est installé (npm install --save-dev gh-pages) et que le build fonctionne (npm run build).

Les modifications ne s'affichent pas → GitHub Pages peut mettre 1-2 minutes à se mettre à jour. Forcez le rechargement avec Ctrl+Shift+R.

Récapitulatif

Ressources