Deploying a React App Using GitHub Pages and GitHub Actions
By: Clyde D'Souza
Tags: Github Pages, Create React App, React, Typescript, Github Actions

Introduction

I recently created a website using the Create React App starter template to demonstrate an npm package I developed. I thought it would be pretty straightforward to deploy this site using GitHub Pages, however, I was wrong. After some trial and error, I managed to sort it out. This article aims at recreating the scenario and walking you through the process of solving each problem we encounter along the way.

#1 Starting point

Let’s start with a common base. We’ll begin by creating a React app using the Create React App utility and also add the code to a GitHub repository. I’ve used the following command to generate this sample React app.

npx create-react-app <project directory> --template typescript

At this point, your project directory should look something like the screenshot below. I haven’t added or modified anything — these are the files and folders that get generated out-of-the-box when we run the npx command stated above. I just made sure it works locally by running the command npm run start and that’s about it.

I’ve pushed these changes to my GitHub repository and if you’re following along, you can do the same, too. This is what my repository looked like at this stage if you want to compare.

#2 Deploying to GitHub pages

When we run the command npm run build , Create React App puts the production files into the build directory. However, if you take a look at the .gitignore file, you’ll see that the build directory is added to this list, thus, preventing you from committing the contents of this folder to GitHub. So, how do we publish our app, then?

GitHub Actions

Let’s bring GitHub Actions to the rescue! We need to build our app every time code is committed and that’s where GitHub Actions comes in. Create a YAML file called build-deploy.yml in the .github/workflows directory of your app. Paste the following contents into this YAML file. This is what my GitHub repository looked like at this stage.

I recently wrote this article explaining the fundamentals of GitHub Actions, so I won’t get into too much detail here. To summarize, this YAML file defines the workflow in GitHub Actions. This workflow will get triggered every time a change is pushed to the main branch or a pull request is created to merge changes to the main branch, it will build the React app and deploy the contents of the build directory to the gh-pages branch.

A quick note on ${{ secrets.GITHUB_TOKEN }} — GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. It comes with write access to the repository, therefore, allowing you to update the gh-pages branch. Read the full list of permissions here.

If you’re following along, commit this file to your repository. Immediately, you’ll notice that GitHub Pages will now build based on what you have in your workflow file. If you head over to the Actions tab in GitHub, you’ll see your workflow being executed and hopefully, after some time, marked as successful. Feel free to click around in the UI and explore this area of your GitHub repository.

Given that the status shows up as successful, this action would have also created a new branch called gh-pages and would have deployed the production-ready code in there.

Easy as, isn’t it?

GitHub Pages

Now that we have our build files placed in a different branch, let’s go ahead and enable GitHub Pages. Click on Settings from the menu and then scroll down to the GitHub Pages section.

Here, we’re going to configure where our website contents are located. Since our build files get pushed to the gh-pages branch, let’s choose that from the dropdown. Click on the Save button. The page will refresh and when you scroll back down to this section, you’ll see a URL. Click on that URL to see the website.

Wait, what happened? I can’t see the React app output, can you?