Deploying a React App to GitHub Pages using GitHub Actions

📝 Summary

In this tutorial, you are going to see how to:

1. Create a new React app.

2. Create a GitHub public repository.

3. Configure GitHub Actions Token Permissions.

4. Setup GitHub Actions workflow: Deploy React app to GitHub Pages.

5. Push the code to your GitHub repository.

6. Enable GitHub Pages sourced by gh-pages branch.

🧰 Step 1: Create a new React app

1. Run the following command to create a new React app:

npx create-react-app app-name

• Replace the "app-name" with the name of your app/project.
• It will take a while since it install all the necessary dependencies.

2. Your app is now created, let's navigate into the new app folder and run the command to execute the app:

cd app-name
npm start

3. This will start the development server, and you should see an output like this:

You can now view react-app in the browser.

  Local:            http://localhost:3000
  On Your Network:  http://---.--.--.-:3000

Note that the development build is not optimized.
To create a production build, use npm run build.

webpack compiled successfully

4. Open your browser and head to http://localhost:3000 and you should see the default welcome page!

🔓 Step 2: Create a GitHub public repository

Go to your GitHub repositories page/tab:

1. In the top right of the page, click on the button "New"
2. Inform the "Repository name"
3. And keep it as a Public repository (Anyone on the internet can see this repository. You choose who can commit.)
4. Then, at the end of the page click on the button "Create repository"
5. And that is it. Your public repository is created!

🔐 Step 3: Configure GitHub Actions Token Permissions

Enable Write Permissions for the GITHUB_TOKEN

1. Settings > Actions > General
2. Scroll down untill the end of the page and in the Workflow permissions section select "Read and write permissions"
3. Optional: You can also check the "Allow GitHub Actions to create and approve pull requests" if needed
4. Click the Save button

🤖 Step 4: Setup GitHub Actions workflow: Deploy React app to GitHub Pages

In the root folder of your project:

1. Set the homepage (base path) at the beggining of the package.json file:

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

2. Create a new folder named .github in the root folder of the project
3. Inside the new .github folder, create a new folder named workflows
4. Inside the new workflows folder, create a new file named deploy.yml
5. Inside the new deploy.yml file, paste the following content:

name: Deploy React App with Vite to GitHub Pages

on:
  push:
    branches:
      - main  # or your default branch

jobs:
  deploy:
    runs-on: ubuntu-latest

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

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Build the app
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build  # This is where are the outputs of the build
          publish_branch: gh-pages  # Optional: default is gh-pages

📂 Step 5: Push the code to your GitHub repository

1. Initialize a git repository in your project

   git init
   git checkout -b main
   git remote add origin https://github.com/your-username/your-repo-name.git
   

   Replace the above url with the one provided in your repository.

2. Push to GitHub:

   git add .
   git commit -m "Initial commit"
   git push -u origin main
   

🧭 Step 6: Enable GitHub Pages sourced by gh-pages branch

In your GitHub repo:

1. Go to Settings → Pages
2. In the "Build and deployment" section:

• For Source, select Deploy from a branch
• For Branch, select the gh-pages branch and root (/) folder
• Click the Save button

🎉 Beatifully your app should be up and running at "https://your-username.github.io/your-repo-name/" (the one you have defined in the package.json file).

👀 You can also check the executed(s) workflow(s) in your repository at the Actions tab. 🚀