Step-by-Step Guide: Hosting Your React App on GitHub Pages

Are you ready to showcase your React app to the world? Look no further than GitHub Pages! In this step-by-step guide, we will walk you through hosting your React app on GitHub Pages so you can easily share your creation with others.

We’ve created a to-do list app; now, let’s deploy it on GitHub Pages.

GitHub Pages is a popular hosting solution that allows you to publish static websites directly from your GitHub repositories.

With its user-friendly interface and seamless integration with Git, hosting your React app has never been easier. Plus, GitHub Pages offers free hosting, making it an ideal choice for personal projects or smaller-scale applications.

Setting up a GitHub repository for your React app

Before you can host your React app on GitHub Pages, you’ll need to create a GitHub repository for your project. If you’re not familiar with GitHub, don’t worry – we’ll guide you through the process.

To start, go to the GitHub website and sign in to your account. Once you’re logged in, click on the “New” button in the top-left corner of the screen and select “New repository” from the dropdown menu.

Give your repository a name and choose whether you want it to be public or private.

Do not include a Readme file in the repository.

Building and deploying your React app to GitHub Pages

Open up your terminal and navigate to the directory where you want to store your project. Then, use the following command to create your React app.

Let’s create a React app using vite

npm create vite@latest

Feel free to use, Yarn or pnpm.

Make sure you select, React as a template. I will select Typescript but you can select other options as well.

After you finish creating the app, navigate to the project folder, initialise git and set the GitHub remote origin of the React app to the GitHub repo we’ve created earlier.

cd gh-pages-pg 
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/Tchoukoualeu/gh-pages-pg.git
git push -u origin main

Remember to change https://github.com/Tchoukoualeu/gh-pages-pg.git to your repository-url, and gh-pages-pg by the name you gave to your project

Open you repository on GitHub, you should see that the files that you have in your local machine are now online.

Let’s intall the app

npm i

Let’s build the React app

npm run build

vite build hosting react app on github pages

This will create a production-ready build of your app in a folder called “dist” in your project directory. Once the build process is complete, you’re ready to deploy your app to GitHub Pages.

Go to your the vite.config.ts file and add the following line: base: "/gh-pages-pg/",

It should look like

vite config while hosting on github pages

Add the current changes and push to main

git add .
git commit -m "adjust vite config"
git push

GitHub Pages has a special branch called “gh-pages” to host your app. To create this branch, run the following command in your terminal:

git checkout -b gh-pages
npm run build

This will create a new branch called “gh-pages” and switch to it. Next, copy the contents of the “dist” folder into the root directory of your project. You can do this by running the following command:

cp -r dist/* .

This will copy all the files from the “dist” folder into the current directory. Finally, commit and push the changes to your GitHub repository:

git add .
git commit -m "Deploy app to GitHub Pages"
git push origin gh-pages

Once the push is complete, your React app will be live on GitHub Pages! You can access it using the following URL:

https://tchoukoualeu.github.io/gh-pages-pg/

Replace tchoukoualeu with your GitHub username and gh-pages-pg with the name of your GitHub repository. It may take a few minutes for the changes to propagate, so be patient if your app doesn’t appear immediately.

Whenever you make adjustments to your app, you’ll need to manually build and update the content of the “gh-pages” branch to ensure that the changes are reflected on your website.

If you use GitHub Actions, your website updates itself whenever you add something new to your main branch. No manual steps needed!

Automatically hosting your React App on GitHub Pages

To do that, add this file to your repo’s root and push the changes to Github.

# .github/workflows/deploy.yml

name: Deploy your React App to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: npm install
        run: npm install
      - name: npm build
        run: npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload static files
          path: "dist/"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Configuring custom domain for your React app on GitHub Pages

By default, your React app on GitHub Pages will have a URL in the format `username>.github.io/repository-name>`. However, if you want to use a custom domain for your app, GitHub Pages supports that too.

To configure a custom domain, you’ll need to make a few changes to your domain’s DNS settings. First, go to your domain registrar’s website and find the DNS settings for your domain. Look for an option to add a new DNS record.

Next, create a new CNAME record with the following details:

– Host: www (or any subdomain you want to use)

– Value: `username>.github.io`

– TTL: 1 hour (or your preferred TTL)

Save the changes to your DNS settings. Then, return to your GitHub repository and navigate to the “Settings” tab. Scroll to the “Pages” section and enter your custom domain in the “Custom domain” field. Click “Save” to apply the changes.

It may take some time for the DNS changes to propagate, so be patient. Once the changes have propagated, you’ll be able to access your React app using your custom domain.

Troubleshooting common issues when hosting a React app on GitHub Pages

While hosting your React app on GitHub Pages is relatively straightforward, you may encounter some common issues along the way. Here are a few troubleshooting tips to help you overcome these challenges.

Images or assets not loading: Double-check the file paths in your code if your images or other assets are not loading on GitHub Pages. Remember that GitHub Pages is case-sensitive, so ensure the file names and paths match exactly.

Custom domain issues: If you are experiencing issues with your custom domain, double-check that you have correctly configured the DNS settings for your domain. Also, remember that DNS changes may take some time to propagate.

Empty page: If your React app is not rendering properly or showing an empty page on GitHub Pages, check your app’s console for any error messages. Ensure all the necessary files are included in your app’s “build” or “dist” directory.

By following these troubleshooting tips, you should be able to resolve the most common issues when hosting your React app on GitHub Pages.

Comparing GitHub Pages with other hosting options for React apps

While GitHub Pages is a great option for hosting React apps, it’s not the only one available. Let’s take a quick look at how GitHub Pages compares to other popular hosting options:

1. Netlify: Netlify is a powerful hosting platform with features like continuous deployment, form handling, and serverless functions. It’s a great choice for more complex React apps that require advanced functionality.

2. Vercel (formerly Zeit): Vercel is known for its seamless integration with Next.js, a popular React framework. If you’re using Next.js for your app, Vercel provides a simple and efficient hosting solution.

3. Firebase: Firebase is a comprehensive platform that offers hosting, database, authentication, and more. It’s a good choice if you’re building a full-stack React app and need additional backend services.

Ultimately, the best hosting option for your React app will depend on your specific needs and requirements. GitHub Pages is a fantastic choice for simple, static React apps, while other platforms offer more advanced features and functionality.

Examples of successful React apps hosted on GitHub Pages

To inspire you and showcase the capabilities of hosting React apps on GitHub Pages, here are a few examples of successful projects:

1. React Calculator: A simple calculator app built with React and hosted on GitHub Pages. This app showcases the basic functionality of React and demonstrates how you can create interactive UI components.

2. React Pomodoro clock: a tool designed to help users effectively manage their time and enhance productivity using the Pomodoro Technique. It typically features an easy-to-use interface where users can set a timer for their work sessions, usually 25 minutes, followed by a short break.

3. Dice Game: roll a pair of dice 10 times, and see if your total beats a random player’s score. The one with the highest total wins

These examples highlight the versatility and potential of React apps hosted on GitHub Pages. You can create impressive projects showcasing your developer abilities with the right skills and creativity.

Conclusion and final thoughts

Hosting your React app on GitHub Pages is a straightforward and cost-effective way to share your creations with the world. This step-by-step guide covered everything you need to know, from setting up a GitHub repository for your app to deploying it on GitHub Pages.

By following the instructions outlined in this guide, you can confidently host your React app on GitHub Pages and reach a wider audience. So what are you waiting for? Start showcasing your React apps today, and let the world see your talent!