Deploying a React Frontend with GitHub Pages and GitHub Actions

Introduction

Deploying a React application shouldn't be complicated. GitHub Pages provides a free and easy way to host static websites, making it a great option for React frontend deployment. However, manually deploying updates can become tedious. This is where GitHub Actions comes in—it automates the process, ensuring that every push to the main branch triggers a new deployment.

In this guide, we'll walk through setting up GitHub Pages for a React app and automating the deployment process using GitHub Actions.

Step 1: Setting Up GitHub Pages for a React App

1.1 Create a React App (If You Haven't Already)

If you don't have an existing React project, create one using:

npx create-react-app my-app
cd my-app

1.2 Configure package.json

Update the homepage field in package.json to point to your GitHub Pages URL:

"homepage": "https://<your-github-username>.github.io/<repository-name>"

Step 2: Automating Deployment with GitHub Actions

o ensure that your React app deploys automatically whenever you push changes to the main branch, we'll use GitHub Actions.

2.1 Create a GitHub Actions Workflow

Inside your repository, create a directory .github/workflows/ and add a file named deploy.yml:

name: Deploy React App

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install dependencies
        run: npm install

      - name: Build the project
        run: npm run build

     - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

The GITHUB_TOKEN is a built-in secret provided by GitHub Actions. It allows workflows to authenticate with GitHub and perform actions such as pushing to the gh-pages branch. This means you don’t need to create a personal access token manually.

The above file assumes you are in the root of your project, If your great app is in another folder, ensure to first navigate to that folder. eg if it is in the frontend folder:

  - name: Install dependencies
        run: |
          cd frontend
          npm install

      - name: Build the frontend
        run: |
          cd frontend
          npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./frontend/build

2.2 Commit and Push the Workflow

Commit the deploy.yml file and push it to main. GitHub Actions will now run automatically whenever you push changes to main.

Step 3: Configuring GitHub Pages in Repository Settings

1. Go to your GitHub repository.

2. Navigate to Settings > Pages.

3. Under Branch, select gh-pages and click Save.

4. Your site should be accessible at https://<your-github-username>.github.io/<repository-name>.

Step 4: Troubleshooting & Common Issues

4.1 404 Not Found

If you see a 404 Not Found error:

• Ensure the homepage field is correctly set in package.json.

• Verify that the GitHub Pages branch is set to gh-pages in repository settings.

4.2 Incorrect Asset Paths

If styles or scripts don't load properly:

• Ensure that all asset paths are relative, or use %PUBLIC_URL% in index.html.

4.3 GitHub Actions Not Triggering

If your GitHub Action is not running:

• Ensure GitHub Actions is enabled under Settings > Actions.

• Check the Actions tab for errors.

Conclusion

By using GitHub Pages and GitHub Actions, you can automate the deployment of your React frontend, ensuring that updates are published with every push to main. This eliminates the need for manual deployments and keeps your workflow efficient.

If you have any questions or run into issues, feel free to drop a comment!