react gh pages

Déploiement d'une application React * aux pages GitHub

* Créé à l'aide de create-react-app

Introduction

Dans ce tutoriel, je vais vous montrer comment vous pouvez créer une application React et la déployer sur les pages GitHub.

Pour créer l'application React, j'utiliserai create-react-app , qui est un outil que les gens peuvent utiliser pour créer une application React à partir de zéro. Pour déployer l'application React, j'utiliserai gh-pages , qui est un package NPM que les gens peuvent utiliser pour déployer des choses sur GitHub Pages, un service d'hébergement Web gratuit fourni par GitHub.

Si vous suivez ce tutoriel, vous vous retrouverez avec une nouvelle application React - hébergée sur les pages GitHub - que vous pouvez ensuite personnaliser.

Traductions

Ce tutoriel a été traduit de son anglais original dans les langues suivantes:

• Chinois traditionnel (crédit: @ crage9487)

Tutoriel

Condition préalable

1. Le nœud et le NPM sont installés. Voici les versions que j'utiliserai lors de la création de ce tutoriel:

   $ node --version
   v16.13.2
   
   $ npm --version
   8.1.2

   L'installation de NPM ajoute deux commandes au système - npm et npx - dont j'utiliserai tout en faisant ce tutoriel.

2. Git est installé. Voici la version que j'utiliserai en faisant ce tutoriel:

   $ git --version
   git version 2.29.1.windows.1

3. Un compte github.

Procédure

1. Créez un référentiel vide sur github

1. Connectez-vous à votre compte GitHub.
2. Visitez le formulaire Créer un nouveau référentiel.
3. Remplissez le formulaire comme suit:

   • Nom du référentiel: vous pouvez saisir n'importe quel nom que vous souhaitez *.

     * Pour un site de projet, vous pouvez saisir n'importe quel nom que vous souhaitez. Pour un site utilisateur, GitHub exige que le nom du référentiel ait le format suivant: {username}.github.io (par exemple gitname.github.io )

     Le nom que vous entrez apparaîtra à quelques endroits: (a) dans les références au référentiel à travers Github, (b) dans l'URL du référentiel, et (c) dans l'URL de l'application React déployée.

     Dans ce tutoriel, je déploierai l'application React en tant que site de projet.

     Je vais entrer: react-gh-pages

   • Confidentialité du référentiel: sélectionnez public (ou privé *).

     * Pour les utilisateurs gratuits de GitHub, le seul type de référentiel pouvant être utilisé avec les pages GitHub est public . Pour les utilisateurs de GitHub Pro (et d'autres utilisateurs payants), les référentiels publics et privés peuvent être utilisés avec des pages GitHub.

     Je vais choisir: public

   • Initialisez le référentiel: laissez toutes les cases à cocher vides.

     Cela le fera ainsi GitHub crée un référentiel vide, au lieu de pré-populant le référentiel avec un fichier README.md , .gitignore et / ou LICENSE .

4. Soumettre le formulaire.

À ce stade, votre compte GitHub contient un référentiel vide, ayant le type de nom et de confidentialité que vous avez spécifié.

2. Créez une application React

1. Créez une application React nommée my-app :

   Si vous souhaitez utiliser un nom différent de my-app (par exemple web-ui ), vous pouvez y parvenir en remplaçant toutes les occurrences de my-app my-app dans ce tutoriel, par cet autre nom ( web-ui ).

   $ npx create-react-app my-app

   Cette commande créera une application React écrite en javascript. Pour en créer un écrit en TypeScript, vous pouvez émettre cette commande à la place:

   $ npx create-react-app my-app --template typescript

   Cette commande créera un nouveau dossier nommé my-app , qui contiendra le code source d'une application React.

   En plus de contenir le code source de l'application React, ce dossier est également un référentiel GIT. Cette caractéristique du dossier entrera en jeu à l'étape 6.

   Noms de branche: master contre main

   Le référentiel GIT aura une branche, qui sera nommée (a) master , la valeur par défaut pour une nouvelle installation GIT; ou (b) la valeur de la variable de configuration GIT, init.defaultBranch , si votre ordinateur exécute GIT version 2.28 ou version ultérieure et que vous avez défini cette variable dans votre configuration git (par exemple via $ git config --global init.defaultBranch main ) .

   Comme je n'ai pas défini cette variable dans mon installation GIT, la branche de mon référentiel sera nommée master . Dans le cas où la succursale de votre référentiel a un nom différent (que vous pouvez vérifier en exécutant $ git branch ), comme main ; Vous pouvez remplacer toutes les occurrences de master dans le reste de ce tutoriel, par cet autre nom (par exemple master → main ).

2. Entrez le dossier nouvellement créé:

   $ cd my-app

À ce stade, il existe une application React sur votre ordinateur et vous êtes dans le dossier qui contient son code source. Toutes les commandes restantes indiquées dans ce tutoriel peuvent être exécutées à partir de ce dossier.

3. Installez le package NPM gh-pages

1. Installez le package NPM gh-pages et désignez-le comme une dépendance de développement:

   $ npm install gh-pages --save-dev

À ce stade, le package NPM gh-pages est installé sur votre ordinateur et la dépendance de l'application React sur elle est documentée dans le fichier package.json de l'application React.

4. Ajouter une propriété homepage au fichier package.json

1. Ouvrez le fichier package.json dans un éditeur de texte.

   $ vi package.json

   Dans ce tutoriel, l'éditeur de texte que j'utiliserai est VI. Vous pouvez utiliser n'importe quel éditeur de texte que vous souhaitez; Par exemple, Visual Studio Code.

2. Ajoutez une propriété homepage dans ce format *: https://{username}.github.io/{repo-name}

   * Pour un site de projet, c'est le format. Pour un site utilisateur, le format est: https://{username}.github.io . Vous pouvez en savoir plus sur la propriété homepage dans la section "GitHub Pages" de la documentation create-react-app .

   {
     "name": "my-app",
     "version": "0.1.0",
   + "homepage": "https://gitname.github.io/react-gh-pages",
     "private": true,

À ce stade, le fichier package.json de l'application React comprend une propriété nommée homepage .

5. Ajouter des scripts de déploiement au fichier package.json

1. Ouvrez le fichier package.json dans un éditeur de texte (s'il n'est pas déjà ouvert en un).

   $ vi package.json

2. Ajoutez une propriété predeploy et une propriété deploy à l'objet scripts :

   "scripts": {
   +   "predeploy": "npm run build",
   +   "deploy": "gh-pages -d build",
       "start": "react-scripts start",
       "build": "react-scripts build",

À ce stade, le fichier package.json de l'application React comprend des scripts de déploiement.

6. Ajouter une "télécommande" qui pointe au référentiel GitHub

1. Ajoutez une "télécommande" au référentiel GIT local.

   Vous pouvez le faire en émettant une commande dans ce format:

   $ git remote add origin https://github.com/{username}/{repo-name}.git

   Pour personnaliser cette commande pour votre situation, remplacez {username} par votre nom d'utilisateur GitHub et remplacez {repo-name} par le nom du référentiel GitHub que vous avez créé à l'étape 1.

   Dans mon cas, je vais courir:

   $ git remote add origin https://github.com/gitname/react-gh-pages.git

   Cette commande indique à Git où je veux que cela pousse les choses chaque fois que je - ou le package NPM gh-pages agissant en mon nom - émettais la commande $ git push de dans ce référentiel GIT local.

À ce stade, le référentiel local a une "télécommande" dont l'URL pointe vers le référentiel GitHub que vous avez créé à l'étape 1.

7. Poussez l'application React au référentiel GitHub

1. Poussez l'application React vers le référentiel GitHub

   $ npm run deploy

   Cela entraînera l'exécution des scripts predeploy et deploy des scripts définis dans package.json .

   Sous le capot, le script predeploy créera une version distribuable de l'application React et la stockera dans un dossier nommé build . Ensuite, le script deploy pousse le contenu de ce dossier vers un nouveau commit sur la branche gh-pages du référentiel GitHub, créant cette branche si elle n'existe pas déjà.

   Par défaut, le nouveau commit sur la branche gh-pages aura un message de validation des "mises à jour". Vous pouvez spécifier un message de validation personnalisé via l'option -m , comme ceci:

   $ npm run deploy -- -m " Deploy React app to GitHub Pages "

À ce stade, le référentiel GitHub contient une branche nommée gh-pages , qui contient les fichiers qui composent la version distribuable de l'application React. Cependant, nous n'avons pas encore configuré des pages GitHub pour servir ces fichiers.

8. Configurer les pages GitHub

1. Accédez à la page Paramètres des pages GitHub
   1. Dans votre navigateur Web, accédez au référentiel GitHub
   2. Au-dessus du navigateur de code, cliquez sur l'onglet intitulé "Paramètres"
   3. Dans la barre latérale, dans la section "code et automatisation", cliquez sur "Pages"
2. Configurez les paramètres "Build and Deployment" comme celui-ci:
   1. Source : Déployer à partir d'une succursale
   2. Bifurquer :
      • Branche: gh-pages
      • Dossier: / (root)
3. Cliquez sur le bouton "Enregistrer"

C'est ça! L'application React a été déployée sur les pages GitHub!

À ce stade, l'application React est accessible à tous ceux qui visitent l'URL de la homepage que vous avez spécifiée à l'étape 4. Par exemple, l'application React que j'ai déployée est accessible sur https://gitname.github.io/react-gh-pages.

9. (Facultatif) Stockez le code source de l'application React sur GitHub

Dans une étape précédente, le package NPM gh-pages a poussé la version distribuable de l'application React à une branche nommée gh-pages dans le référentiel GitHub. Cependant, le code source de l'application React n'est pas encore stocké sur GitHub.

Dans cette étape, je vais vous montrer comment vous pouvez stocker le code source de l'application React sur GitHub.

1. Engagez les modifications que vous avez apportées pendant que vous suiviez ce tutoriel, à la branche master du référentiel GIT local; Ensuite, poussez cette branche vers la branche master du référentiel GitHub.

   $ git add .
   $ git commit -m " Configure React app for deployment to GitHub Pages "
   $ git push origin master

   Je recommande d'explorer le référentiel GitHub à ce stade. Il aura deux branches: master et gh-pages . La branche master contiendra le code source de l'application React, tandis que la branche gh-pages contiendra la version distribuable de l'application React.

Références

1. Le guide officiel de déploiement de create-react-app
2. Blog GitHub: construire et déployer des pages github à partir de n'importe quelle branche
3. Préserver le fichier CNAME lors de l'utilisation d'un domaine personnalisé

Notes

• Un merci spécial à GitHub (la société) de nous avoir fourni gratuitement le service d'hébergement GitHub Pages.
• Et maintenant, il est temps de transformer l'application React par défaut générée par create-react-app en quelque chose d'unique!
• Ce référentiel se compose de deux branches:
  • master - Le code source de l'application React
  • gh-pages - L'application React construite à partir de ce code source

Contributeurs

Merci à ces personnes d'avoir contribué à la maintenance de ce tutoriel.

Cette liste est maintenue manuellement - pour maintenant - et comprend (a) chaque personne qui a soumis une demande de traction qui a finalement été fusionnée dans master , et (b) chaque personne qui a contribué d'une manière différente (par exemple, fournir des commentaires constructifs) et qui a approuvé de moi y compris dans cette liste.