How to host react websites on GitHub. A comprehensive guide!

5 min readJan 26, 2024

React websites can be hosted on a number of platforms. One of the options here is to host these on GitHub.

Now, there are a lot of tutorials out there that teach you how to do exactly that. But there are some quirks involved that you might not be able to solve if you are new to gh-pages and or GitHub and or React.js and or to the entire web development thing!

When the first time I wished to try gh-pages for my react sites, I followed a few tutorials & guides but had to give up after a few failed attempts. It’s not that the tutorials were wrong, it’s just that they didn’t address & explain the hidden quirks very well.

After a while I somehow figured it out and felt the need to jot it down in order to save hassle for others. In this tutorial first, we are going to create a React.js site with create-react-app, then we are going to configure gh-pages to host it on GitHub, and then finally deploy it on GitHub.

Alright! So let’s get started.

Note: You need to have node.js, npm, git installed on your machine.

Scaffold a react.js website

Go to the root directory where you want to create the site. Then cd into that folder in your CLI and type the following command:

$ npx create-react-app github-hosted-react-site

When your react site is done scaffolding, cd into your project folder:

$ cd github-hosted-react-site

Now to preview your React.js Site fire up the local server:

$ npm start

In your browser at http://localhost:3000/, you’ll see a template react site. For brevity, we are not modifying this and will be deploying this template site.

Make a production build

Note: before doing anything in the CLI make sure you kill any running server. Usually done with CTRL+C

To deploy our site on GitHub we just have to compile all the React code and place it in the root of a directory somewhere, all you need to do is run the following line:

$ npm run build

Now we have a production build ready to be deployed.

Configure gh-pages

Note: before doing anything in the CLI make sure you kill any running server. Usually done with CTRL+C

Now install gh-pages & save it as a dependency in our project:

$ npm i -s gh-pages

Now add a homepage field to the package.json file that has the URL we want our app to be live on. With the homepage field, we can control where the final site should be hosted on our repo.

"homepage": "https:/your-username.github.io/github-hosted-react-site/"

Now initialize the project folder as a git repository with:

$ git init

Having accomplished it, now add a remote of the repository whose gh-pages URL you are aiming for.

$ git remote add origin https:/github.com/your-username/github-hosted-react-site

This is necessary for gh-pages to identify which repo to use as a target, that repo shall be added as a remote in your local one. The homepage field is just for the URL purpose.

Note: The url which you added as a remote is the url of the master branch of your repository.

Now, move into the package.json file and add the following scripts above all others:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -b master -d build"
}

Note: Here focus on the deploy command. This says to gh-pages with the -b flag that our master branch will be used to deploy with the -d flag, the build folder that has our compiled, production-ready code. The “-b master” is necessary as gh-pages by default deploys to the gh-pages branch.

Even if you don’t have one in your repository it will create one for you and then use it for the deployment process. Now you’ll wonder what’s wrong with deploying to the gh-pages branch.

So remember which URL we added as a remote for our local repo? It was the master branch’s URL. All the branches on GitHub have different URLs.

Similarly, the default gh-pages URL has a different URL than the master branch.

In our case it’s https://github.com/your-username/github-hosted-react-site/tree/gh-pages.

So if you don’t include the -b master thing in the deploy field you’ll see a 404 once you deploy as the gh-pages is deploying on the gh-pages branch while the site URL is of the master branch. So it’s like aiming at one thing & shooting at another.

However, in case you want to host your site on the gh-pages branch, just remove the -b master part from the deploy field. Also, do not forget to add the url of your gh-pages as a git remote in your local repo. The homepage field remains unchanged.

Phew, Now Let’s Deploy.

Create a build with:

$ npm run build

Then deploy with:

$ npm run deploy

And we are done!

Now your site will be available at https://your-username.github.io/github-hosted-react-site/.

In case this doesn’t work for you do let me know in the comments what problem you are facing. I’ll try to help if I can.

You need to be very careful when using routing in your react site. There are a few things to take care of like whether the router you are using, uses the history-api or not. Maybe we’ll cover it on some other day.

About Me

I’m a Senior Product Engineer from India, working in web and mobile development. I enjoy turning complex problems into simple, beautiful, and intuitive software. I blog to share my software knowledge with others.

My job is to build your idea so that it is functional and user-friendly but at the same time attractive. Moreover, I add a personal touch to your product and make sure that is eye-catching and easy to use. I aim to help you validate and scale your startup most creatively.