Hosting a React App Using Github Pages | Helpfulz

Hosting a React App Using Github Pages

July 12, 2019

I’d like to clarify some “gotcha’s” when trying to host a React App to Github Pages using the “react-gh-pages” npm package. I believe this package is great and it has met my needs several times. 

This guide is geared towards a more beginner audience.

The README file on this repo is really quite good, but I’d like to fill in some gaps. Here’s why I feel this guide is useful:

  1. It is assumed that we will start from scratch, as per the README file. But what if we are not starting from scratch, then what do we do?
  2. You may not quite understand what is going on, and would like further insight into how it works.
  3. You may have never modified your package.json file and may not be sure if you’ve done it right.

I’m going to deploy an existing project that I already have on Github to Github pages and cover the gaps that I feel are missing. I’m starting from a React App that I already have the code stored in Github, however it is not hosted yet. I originally created this project using the create-react-app package

  1. First thing, make sure the project builds and runs locally. This small precaution may save you a lot of headache.

You should start with the README file from the repo. I’m going to glide through the instructions in the README as it covers most things, and then there are parts that I don’t do… so bare with me.

I’m assuming your are using sufficiently recent versions of node, npm and create-react-app as per the README. The README uses sed which I skip.

The first major mistake that I see students making is this, they will have the Github Repo folder, and then the create-react-app folder inside. The file structure would look something like this, which is wrong by the way:


└── create-react-app-folder

    └── this-represents-all-the-react-files.js

This doesn’t work because Github needs to see the react files at the very root folder of the repo. This is how it should look (representation):


    └── this-represents-all-the-react-files.js

Ok, now that we have the file structure in place, we’re going to make the first change to our “package.json” file.

Let’s add:

"homepage": ""

to our file. In the end my file looks like this:

// Link to package.json here

Make sure that you put in your own Github Name and project name. For example mine looks like this:


The package.json file is of course a json file, so you’ll need to add appropriate coma’s to avoid errors. Please refer to my full package.json file link above to see what it should look like. Also make sure you spell your username right and the repo name.

Ok so we have avoided common mistakes on the package.json file. Well we have a few more change to make so we’re not done yet.

The next step is very black and white, just make sure you don’t miss a coma somewhere or a quotation mark.

  • In the existing scripts property, add a predeploy property and a deploy property, each having the values shown below:
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"

For me the easiest way to do this is to look for the “scripts” section and just add these two commands down at the bottom. No need to delete the other scripts commands that are already there.

Ok now the instructions go through the process of initializing the folder as a git folder. Since we are starting from projects that are already deployed to Github we can skip that.

Head over to your favorite terminal (bash / gitbash / terminal / etc …) that you use for your project. Navigate to the root folder of your project. Let’s make sure we have the npm package installed in order to deploy the project:

npm install gh-pages --save-dev

The next step is to run the magic command:

npm run deploy

After this has been done there is still one more step we need to do back on the site. Let’s head over to our repo homepage on Github. If you followed the instructions properly and everything ran well, you should notice that there is a new branch on your GitHub repo called “gh-pages”.

Screen Shot 2019-07-12 at 12.29.49 AM

This is how it should be. Click on the settings button on the top right

Screen Shot 2019-07-12 at 12.31.35 AM

and scroll down to the section called “Github Pages”. Ensure that the “gh-pages” branch is selected.

Screen Shot 2019-07-12 at 12.33.01 AM


So there you have it. Sometimes it can take 5-10 minutes for GitHub pages to reflect your project. This is also true for non-react projects on Github pages..

A little bit more on the way this works. So GitHub pages will only host static pages for you, basically HTML, CSS, and Javascript. It will not build any packages for you and it will not interpret React code into stuff your browser can read.

But it will host a proper Build bundle. This is what gh-pages is doing, it builds a static page based off of your React code and then deploys it to a special branch in your GitHub repo. This is why you see a new branch being created and also why we used that branch as the source for your GitHug pages setting.

That’s about it for this. I hope this helped you get up and running. If you think that I skipped an important step or have some other feedback, please let me know!

Profile picture

Written by IzzleNizzle who can be found playing around in the mountains of Utah. ⛰️ You should follow Iz on Twitter

© 2022, Built with Gatsby and WordPress