Nous allons voir ces deux méthodes dans cet article.

Avant de commencer, il est nécessaire de versionner notre projet Angular sur un repository GitHub. Si ce n’est pas déjà fait, je vous invite à créer un nouveau repository public sur GitHub et à versionner votre application Angular.

Pour générer le bundle d'un application Angular, nous devons utiliser la commande ng build.

Premièrement, nous devons modifier le dossier de destination de cette commande qui est par défaut le dossier dist et non le dossier docs.

Deuxièmement, nous devons changer l'url de base de notre application car notre elle ne sera pas disponible à la racine d'un domaine mais sur l'url suivante :

Pour générer notre bundle tout en changeant le chemin de destination et l'url de base de notre application, nous devons exécuter la commande ng build avec les paramètres output-path et base-href.

Lorsque l’on génère le bundle d’une application Angular en version 16 ou inférieure, et que le SSR n’est pas activé, le dossier généré contient directement les fichiers du bundle de notre application.

Avec Angular 17, peu importe si le SSR est activé ou non, le bundle de notre application contient un sous-dossier browser qui contient nos fichiers statiques.

Pour fonctionner avec GitHub Pages, nous ne pouvons pas garder cette arborescence, il faut déplacer les fichiers du dossier browser au dossier docs. Cela peut se faire à la main ou avec un script.

Lorsque l'on héberge des fichiers sur GitHub Pages, si le chemin demandé par l'utilisateur ne correspond pas à un fichier existant, alors GitHub Pages va renvoyer une erreur 404.

Cela va nous poser problème parce que nous travaillons avec une Single Page Application qui doit gérer plusieurs routes, alors que nous n'avons qu'un seul fichier index.html.

Cela veut dire que si, par exemple, l'utilisateur accède directement à l'url suivante :

L'utilisateur va recevoir une erreur 404.

La solution de contournement pour faire fonctionner une Single Page Application sur GitHub Pages est de dupliquer le fichier index.html de notre bundle et de nommer ce nouveau fichier 404.html.

Ainsi GitHub Pages nous renverra ce fichier 404 lorsqu’il ne trouve pas un fichier, ce qui va nous permettre de bien charger notre Single Page Application.

Une fois que notre dossier docs contient les fichiers du bundle de notre application Angular et le fichier 404.html, il ne nous reste plus qu’à commit le dossier docs et push sur notre branche.

Enfin, nous devons configurer notre repository GitHub en lui indiquant sur quelle branche doit se baser GitHub Pages et sur quel dossier.

Pour cela, allez dans Settings de votre repository, puis Pages, et choisissez la branche que vous souhaitez et le dossier /docs.

Enregistrez ces paramètres en cliquant sur Save. Une fois sauvegardé, nous pouvons aller voir dans les Actions du repository pour voir les workflows en cours d’exécution, dont le déploiement de votre application.

Notre application est maintenant disponible à l’url suivante :

La deuxième méthode consiste à fournir directement les fichiers de notre bundle à la racine de notre repository.

Il est possible d’avoir par exemple votre projet Angular entier sur la branche main et uniquement le bundle de votre application sur la branche gh-pages.

Mais générer le bundle depuis une branche et le copier coller sur la branche gh-pages est une opération qui peut être fastidieuse et répétitive. Le but ici n’est pas de le faire manuellement mais d’utiliser un package qui nous facilitera la tâche.

Le package angular-cli-ghpages nous permet justement de facilement déployer notre application sur GitHub Pages en générant notre bundle directement dans le dossier root (à la racine) de la branche gh-pages.

Le package se charge automatiquement d'ajouter le fichier 404.html pour faire fonctionner notre Single Page Application.

Et un autre avantage pour les applications avec Angular 17 ou avec du SSR, est que le package va automatiquement utiliser le contenu du dossier browser de notre bundle.

Pour utiliser le package, il suffit de l'installer avec la commande suivante :

Une fois installé, il suffit d'exécuter la commande suivante à chaque fois que nous voulons redéployer notre application.

Une fois exécutée, nous pouvons retrouver les fichiers de notre bundle sur la branche gh-pages.

Il ne nous reste plus qu'à configurer notre repository GitHub en lui indiquant sur quelle branche doit se baser GitHub Pages et sur quel dossier.

Pour cela, allez dans Settings de votre repository, puis Pages, et choisissez la branche gh-pages et le dossier root.

Enregistrer ces paramètres en cliquant sur Save, puis l'application va se déployer sur GitHub Pages.

Nous avons vu comment déployer et héberger notre application Angular sur GitHub Pages et comment faire fonctionner une Single Page Application en ajoutant le fichier 404.html.

Nous avons vu deux méthodes, le dossier docs et le dossier root. Nous avons aussi appris comment utiliser le package angular-cli-ghpages qui nous facilite grandement la tâche pour déployer notre application.

Parmi ces deux méthodes, je vous conseille la méthode du dossier root avec le package angular-cli-ghpages. Cela vous évite de versionner votre dossier /docs au milieu de votre projet Angular et le package facilite grandement le déploiement sur le dossier root de la branche gh-pages.

Héberger son application sur GitHub Pages est plus adapté pour des projets de tests ou pour ajouter une démonstration de notre projet Angular.

Pour héberger une application Angular en production et pour qu'elle soit SEO-Friendly afin générer du trafic naturel, je vous invite à aller voir ma formation Angular SEO.