How to Create and Deploy a React.js App to Github Pages

What is React? React is an open-source, front end, JavaScript library for building user interfaces or UI components. Most prefer using React.js for their front end because it allows web developers to create large web applications that change data — without reloading the page. React.js is fast, scalable, and simple to use, and one of the things I like most about React is reusable components and fast updating speeds. This tutorial assumes you have Node.js installed already. (If you use yarn , replace the npm commands in this tutorial with yarn .)

Creating a React.js App

One of the easiest ways to create a React app is by using create-react-app. In your terminal, run the command -

npx create-react-app <name>

Change <name> to whatever you want to name your project. It takes a while to create a react app — it needs to install and add a lot of packages and dependencies, so give it a minute or two.

How Do I Get Started?

Once the app is built, open the folder create-react-app created for your project. It should say in your terminal where the folder is. The message is towards the end, and should say something like:

Success! Created project1 at /Users/admin/react_tutorial/project1

Here’s a screenshot of what the starting App.js looks like:

As you can see, there is some starter code to work with. You can run the project by using the commands:

npm run start

or

yarn start

Use either one works best for you. Once you run your project, it should look like this:

All set!

So if I were to make an edit to the App.js, and switched back to the local host tab -

Ta da!

No need to rebuild or restart a server — React.js is fast at updating.

Deploying to Github Pages

Once you’ve polished your React.js app and made a Github repository and pushed your changes, you’ll probably want to deploy. In the settings tab of your Github Repository, scroll down until you see “Github Pages.” You’ll want to enable Github Pages by clicking the drop down menu on “branch” and selecting main (for now). Use the /(root) folder, since you’re going to use everything. Make sure you save!

If you go to the URL it generates at this step, you’ll get a 404. That’s because we haven’t configured the project yet. I’ll go over what to do in these next steps.

In order to deploy your react app to Github pages, make sure you have the Github pages dependency installed. The command to do so is:

npm install gh-pages --save-dev

Double check if it has installed correctly by referring back to the package.json file in your project’s directory. It should be under “dependencies” or “devdependencies”.

My Project’s package.json

Once gh-pages is successfully installed, go to the top of your package.json and add this:

"homepage": "http://{username}.github.io/{repo-name}",

Change {username} to your Github username, and {repo-name} to the name of your repo.

Then, search your package.json file for something that looks something like this:

"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},

These scripts are the equivalent of running npm start , meaning that when you type npm start in your terminal, it also runs react-scripts start .

We need to add commands to our scripts which adds all the necessary dependencies and deploys our project to Github pages.

Our first command is "predeploy": "npm run build" which builds the project and installs necessary dependencies and packages.

The second command is "deploy": "gh-pages -d build" which is what we’ll want to run when we deploy to Github pages.

The end product should look something like this:

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

Once you’ve made sure everything is in the right place, test out your scripts by typing npm run predeploy and then npm run deploy .

Now, commit, and push your changes to your Github repository.

Go back to your settings tab, and down to “Github Pages.” Change your branch from “main” to “gh-pages”, as shown below:

Save, and then npm run predeploy and npm run deploy once more if needed.
On the front page of your Github Repo, under Environments, it should say github pages. Click this link, and your deployment log should come up, and looks something like this:

Click the most recent deployment, under “view deployment.” You should see your React app!

Issues with Images?

A common issue some of my peers experience is that the images on their pages will not show up after deployment. Make sure your <img src> is leading to the correct file or folder.

For example, if your <img src> looks something like this:

<img src={`${process.env.PUBLIC_URL}images/${img}`}/>

Github Pages will read it as:

<img src=yourprojectnameimages/image.png>

which will throw a 404, and your images will not show up.

You can remedy this issue easily by added a / after the public url, so it would look like this:

<img src={`${process.env.PUBLIC_URL}/images/${img}`}/>

Blank Screen?

If you’ve deployed to Github pages and see nothing but a white screen, try changing the homepage url in the package.json to include the https:// in front of the URL.

Example: "homepage": "https://myusername.github.io/myproject/"

Conclusion

React is fast and easy, and deploying on Github pages is fairly simple. I have deployed a few React projects myself to Github pages, and it is highly recommended you only deploy static websites to Github pages, not dynamic websites (ex: a website that has a MongoDB).