Déployez des applications Vite TypeScript sur GitHub Pages sans commiter le dossier dist

L’intégration continue pour un frontend Vite + TypeScript vise souvent GitHub Pages. Une erreur fréquente consiste à commiter l’arborescence dist générée dans la branche par défaut. Le flux de travail présenté ci-dessous évite d’inclure ces artefacts dans Git : Actions compile à chaque mise à jour, télécharge temporairement les résultats et les publie via l’API de déploiement de Pages.

Pourquoi éviter de suivre le dossier dist ?

Les résultats générés doivent rester en dehors du contrôle de version pour plusieurs raisons :

1. Encombrement du répertoire : Les fichiers compilés sont volumineux et nombreux ; les applications mobiles ou à fort contenu graphique peuvent rapidement atteindre leurs limites de taille.
2. Conflits de fusion : Les fichiers régénérés entrent en conflit entre les branches, même lorsque les modifications sources ne sont pas liées.
3. Confusion : Les reviewers perdent la distinction entre le code source modifiable et les produits de compilation opaques.

Pratique CI/CD : Les artefacts doivent être éphémères et générés sur demande.

Mise en place du projet

Créez une application TypeScript React avec Vite :

npm create vite@latest my-app - - template react-ts
cd my-app
npm install

On s’attend à un layout similaire à :

my-app/
├── src/
│ ├── App.tsx
│ ├── main.tsx
│ └── …
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
└── .gitignore

Configurer Vite pour GitHub Pages

GitHub Pages héberge les sites de projet sous un sous-chemin du répertoire, donc Vite a besoin d’une base explicite. Mettez à jour vite.config.ts :

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

export default defineConfig({
 plugins: [react()],
 base: '/your-repo-name/', // Replace with your repository name, in my case: "github-pages-deploy"
})

Ajouter l’URL de base à votre routeur (si vous utilisez React Router)

Les routeurs côté client doivent partager ce sous-chemin via basename :

import { BrowserRouter } from 'react-router-dom'

function App() {
  return (
    <BrowserRouter basename="/your-repo-name/">
      {/* Your routes */}
    </BrowserRouter>
  )
}

Mettre à jour .gitignore

Continuez à ignorer les résultats de la compilation :

# .gitignore
node_modules
dist
dist-ssr
*.local

Créer le workflow GitHub Actions

Ajoutez .github/workflows/deploy.yml :

name: Deploy to GitHub Pages

on:
  push:
    branches: ['main']  # or 'master'
  workflow_dispatch:    # Allow manual trigger

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: 'pages'
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Comprendre le workflow

Le pipeline repose sur quatre principes :

1. Déclencheur : s’exécute lors de dépôts dans la branche main (et permet également un déclenchement manuel).
2. Tâche de compilation : installe les dépendances et génère le fichier dist.
3. Chargement de l’artefact : stocke le fichier dist en tant qu’artefact d’Actions — jamais sous forme de commit Git.
4. Tâche de déploiement : publie cet artefact via GitHub Pages.

En bref : le répertoire reste uniquement une source, Actions conserve temporairement le résultat de la compilation, et Pages sert les fichiers téléchargés.

Configurer GitHub Pages

1. Ouvrez le répertoire sur GitHub.
2. Allez dans Settings → Pages.
3. Sous « Build and deployment », sélectionnez GitHub Actions comme source afin que Pages cesse d’attendre une publication depuis une branche ou un dossier docs.

Tester votre déploiement

Suivez le chemin complet :

1. Push vers main:

git add .
git commit -m "Initial setup with GitHub Actions deployment"
git push origin main

1. Voyez l’exécution sous l’onglet Actions.
2. Lorsque c’est réussi, ouvrez https://your-username.github.io/your-repo-name/.

Conclusion

Le pipeline résultant :

• Construit automatiquement l’application Vite + TypeScript
• Publie sur GitHub Pages sans commiter le dossier dist
• Garde le répertoire limité aux fichiers sources
• Ré déploie à chaque push remplissant les conditions

Séparer les sources des artefacts facilite la collaboration et diminue les surprises lors du déploiement. Réexécutez des tests après de gros changements dans le flux de travail ou la routage, et assurez-vous que le YAML reste cohérent à mesure que le projet évolue.

Préférez échouer de manière visible lors de l’exécution du job Actions en cas d’erreurs de npm run build plutôt que de publier un fichier dist incomplet. Fixez la version de Node dans le workflow pour qu’elle corresponde à celle utilisée en développement local, afin que les fonctionnalités comme le chaining optionnel ou les dernières fonctionnalités de TypeScript fonctionnent sur un ordinateur portable et échouent sur le serveur d’exécution. Lorsque le site utilise un domaine personnalisé, n’oubliez pas que GitHub Pages nécessite toujours la même discipline concernant le base et le basename du routeur que pour un URL de type project-pages sous username.github.io/repo. Un dépôt d’exemple public sous le nom barreiradlc/github-pages-deploy montre ce même schéma, et GitHub Pages peut héberger la démonstration générée à partir de ce projet.