How to Host your React App on GitHub Pages

Deploy, Host React app to GitHub Pages Featured Image

In this post, we will discuss how to host your React App on GitHub pages. I am assuming you took your own sweet time creating your React App which means a lot to you. Now, after such hard work, you must be wondering how can I showcase my project to others. This is a perfect opportunity to deploy our application, there are many options in the market to deploy our React App which includes paid servers. However, if you are looking for deploying your casual application, GitHub pages are the best solution out there and it’s Free.

For real-world applications that are going to serve a large number of clients every day, I would suggest paid servers. But, I will be assuming that you want to deploy your application which will be accessed by a fewer number of clients.


  1. A working GitHub account, and basic knowledge of GitHub repositories.
  2. Node and npm should be installed and working.
  3. A React Application (In case you don’t have one just host the default React Application which you can remove/update later).
NOTE: In case you have a prexisting project ensure that you are using the HashRouter and not the BrowserRouter. For more information read this.

Creating A GitHub Pages Repository (one time)

If you have a repository by the name {yourusername} you can completely skip this step. Now that you are reading I assume you don’t have the repository, so let’s create the repository needed for GitHub Pages. Go over to Github and click on create a new repository and name the repository the following:

GitHub Pages repository for ``

Now an empty repository will be created for you, ensure that it has been created by checking your repositories.

Getting React Application Ready

Before we host React App on GitHub Pages, I want you to ensure that the project is error-free and running as expected. In this post, I will be deploying this project of mine.

1. Adding gh-pages to dev dependencies

To deploy our application to GitHub pages, we will be using gh-pages dependency. However, we will be installing it as a dev-dependency. Simply run the command on the cmd:

npm install gh-pages --save-dev

After this your package.json will contain this dependency as well:

 "devDependencies": {
    "gh-pages": "^4.0.0" // -> New Dependency added

2. Setting up package.json

Open your package.json and add the following properties. Firstly, let’s insert the homepage parameter the value should be in the following format :

"homepage" : "https://{githubusername}"

Note the repo-name as it will be required in the ahead steps. We will store the code and the build in the repository itself. The homepage property for my chat-app-frontend application will look like this:

  "name": "chat-app-frontend",
   // NOTE:  Rename amannegi to your githubusername and chat-app-frontend to your project name
  "homepage":"", // <- add this
  "version": "0.1.0",
  "private": true,

   ... others

Next, we will add the scripts in package.json needed to deploy the app:

  ... others

  "scripts": {
    "predeploy": "npm run build", //<--- add this
    "deploy": "gh-pages -d build", // <--- add this
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"

Creating a GitHub repository to store our Project and Build files

In this step, we will create a repository where we will store our build and project files. It is optional to save the project files however if you want to save the project code files we will be doing that as well. Our repository will have two branches:

  1. main: The code of the project will be stored here.
  2. gh-pages: The build files of the project will be stored here.
React App Repository branches.
The branched structure of the repository

1. Uploading the Project files

To store the code we will create a repository with the same name as the project-folder-name. For example, in my case, the application name is chat-app-frontend so I will create an empty repository by the name of chat-app-frontend. After it has been created on GitHub let’s push the code of our project over to this repository.

To push the code to the repository we will run the following commands, one by one on the cmd:

git init
git add .
git commit -m "Initial Commit"
git remote add origin [email protected]:amannegi/chat-app-frontend.git
git push -u -f origin main


Replace the highlighted section, with {yourgithubusername}/{repo-name}.git in my case, it is amannegi/chat-app-frontend.git.

After running these commands your code will be pushed over to GitHub and you can check it by visiting over to{username}/{repo-name}. The project’s source code has been stored in the repository branch. In case you rammed into an error you can check this post by DigitalOcean to troubleshoot the issue.

2. Uploading the Build files

If you skipped the previous step ensure that you do have an empty repository over on GitHub by the name of your project. Uploading our Build files is a simple step, we just need to run a command and the build will be generated and deployed automatically. Simply run the command we added earlier:

npm run deploy

After this command gets executed the build files will be pushed over to your GitHub repository under the gh-pages branch. Now your build files are hosted on GitHub however the GitHubPages is not configured to host pages from your repository we will set that in the next step.

Finally, setting up the GitHub pages to serve our application

Go over to your GitHub Repositories and open the repo you created during this tutorial where we saved the code and the build. Click on the branches and you should see two branches main and gh-pages. In case you did not upload the code you will only see the gh-pages branch.

Image showing branches of my repository. Part of How to host your React App on GitHub pages on
You can see I have two branches main and gh-pages

Click on the settings of the repository and under the pages section select gh-pages as branch and select /root as the second option.

Change the branch to gh-pages and directory to /root

Click on the Save button, and your React app is ready to be viewed on the URL specified on the page shown above, which has a structure like this:


In my case, the URL for my hosted application is:

Finally, we have answered the question, of how to host React app on GitHub Pages. The app is now live and working on the generated GitHub URL.


I hope your React application is now up and working on GitHub pages, you don’t need to remember everything you can come back anytime to check the syntax again. I am excited to see what innovative React apps you host on GitHub pages. In case you are stuck in any of the steps, you can comment below and I will be happy to help you out.

A similar detailed post is available if you want to host your Flutter web app on GitHub Pages. If you liked this post, you might also like some other detailed posts on Flutter:

Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
DraggableScrollableSheet in Flutter

DraggableScrollableSheet in Flutter

Next Post

Experience of my First Hackathon: MLH #HackFit2