Deploying a React App* to GitHub Pages

* created using create-react-app

Introduction

In this tutorial, I'll show you how I created a React app, then deployed that React app to GitHub Pages.

To create the React app, I used the create-react-app npm package. To deploy the React app to GitHub Pages, I used the gh-pages npm package.

You can visit the deployed React app, here: https://gitname.github.io/react-gh-pages

This repository

This repository consists of two branches:

• master - this branch contains the React app's source code.
• gh-pages - this branch contains the React app built from that source code.

Tutorial

Prerequisites

1. Node.js and npm are installed. Here are the versions I used while writing this tutorial:

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

   Note: During the Node.js installation process, I opted to install npm automatically. Installing npm adds both the npm and npx commands to my system.

2. Git is installed. Here's the version I used while writing this tutorial:

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

   Note: I will be using the command-line Git client in this tutorial.

3. A GitHub account.

Procedure

1. Create an empty repository on GitHub

• In this step, I'll use a form on GitHub to create an empty repository named react-gh-pages in my GitHub account.

  By "empty," I mean one that contains no files.

  To do that, I'll sign into my GitHub account, then fill out the following form:

  • ✍️ Create a new repository

  When filling out the form, I'll enter the name I want the repository to have, which is react-gh-pages.

  In this tutorial, I'll be using a repository named react-gh-pages. In case you're using a repository that has a different name, you can replace all occurrences of react-gh-pages in these instructions with the name of the repository you're using.

  I want the repository to be empty. So, in the "Initialize this repository with" section of the form, I'll leave all the checkboxes empty so GitHub doesn't initialize the repository with any files (i.e. README.md, .gitignore, or LICENSE).

  At this point, my GitHub account contains an empty repository named react-gh-pages.

2. Create a React app

• In this step, I'll use create-react-app to create a React app named my-app.

  $ npx create-react-app my-app

  That command will create a React app written in JavaScript. To create one written in TypeScript, you can issue this command instead:

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

  Either command will create a new folder named my-app, which will contain the newly-created React app.

  I'll enter the new folder.

  $ cd my-app

  All of the remaining commands shown in this tutorial can be run from that new folder.

  Foreshadowing: In addition to containing the files that make up the React app, that new folder is also a Git repository. I will utilize that characteristic in step 6.

3. Install the gh-pages package as a development dependency

• In this step, I'll install the gh-pages package in a way that also designates it as a development dependency of the React app.

  $ npm install gh-pages --save-dev

  That command both (a) installs the gh-pages package and (b) adds its name and version number to the devDependencies section of the package.json file.

4. Add the app's base URL to the package.json file

• In this step, I'll add a homepage property to the package.json file.

  To edit the file, I'll use a code editor such as vi or Visual Studio Code.

  $ vi package.json

  The value of the homepage property is the URL at which I want people to be able to access the React app.

  Since I'll be deploying the React app as a GitHub project page, I'll use this URL format: https://{username}.github.io/{repo-name}

  Here's what the resulting property looks like:

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

  That URL format will allow me to deploy the React app as a GitHub project page. If, instead, I wanted to deploy the React app as a GitHub user page and/or I wanted it to have a custom domain name, I could do so by using one of the URL formats shown in the official create-react-app GitHub Pages deployment guide.

5. Add deployment scripts to the package.json file

• In this step, I'll add some deployment scripts to the package.json file.

  I'll add these two scripts to the scripts object:

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

  That deploy script will allow me to deploy the React app as a GitHub project page. If, instead, I wanted to deploy the React app as a GitHub user page (regardless of domain name), I could do so by using the deploy script shown in the official create-react-app GitHub Pages deployment guide.

6. Add the GitHub repository as a remote

• In this step, I'll add a remote to the local repository.

  That remote will be named origin and will point to the repository I created in step 1. The URL format is: https://github.com/{username}/{repo-name}.git

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

  That will make it so that, when I (or the gh-pages npm package acting on my behalf) perform a git push, Git knows where it can send the files being pushed.

7. Deploy the React app to GitHub

• In this step, I will do two things:

  1. Build a distributable instance of the React app
  2. Deploy that distributable instance of the React app to GitHub

  To do both of those things, I'll issue this one command:

  $ npm run deploy

  That will cause the predeploy and deploy scripts defined in package.json to run.

  Under the hood, the predeploy script will build a distributable version of the React app and store it in a folder named build. Then, the deploy script will push the contents of that folder to the gh-pages branch of the GitHub repository.

  GitHub Pages will automatically detect that files have been pushed to the gh-pages branch of the GitHub repository. Once it detects that, it will begin serving those files — in this case, the distributable version of the React app — to anyone that visits the URL I specified in step 4; i.e. the app's base URL.

  That's it! The React app is now accessible at its base URL: https://gitname.github.io/react-gh-pages 🚀

8. (Optional) Commit the React app's source code to the master branch

• In the previous step, the gh-pages npm package pushed the distributable version of the React app to a branch named gh-pages in the GitHub repository.

  In this step, I will push the source code of the React app to a branch named master in the GitHub repository.

  To do that, I'll issue the following commands:

  $ git add .
  $ git commit -m "Create a React app and deploy it to GitHub Pages"
  $ git push origin master

  I recommend exploring the GitHub repository at this point. It will have two branches: master and gh-pages. The master branch will contain the React app's source code, while the gh-pages branch will contain the distributable version of the React app.

References

1. The official create-react-app deployment guide

Notes

• Special thanks to GitHub (the company) for providing us with the GitHub Pages hosting service for free.
• And now, time to turn the default React app generated by create-react-app into something unique!