How to Host a React App on GitHub Using GitHub Pages

Deploying your React application on the web shouldn’t be complicated — and with GitHub Pages, you can do it for free. Whether it’s a portfolio, a prototype, or a full-featured single-page application, GitHub provides a fast and easy hosting solution for React apps.

In this guide, you’ll learn step-by-step how to deploy a React app to GitHub Pages using the gh-pages package.

---

🚀 Why Host React on GitHub Pages?

• Free and reliable static site hosting
• Integrated with GitHub, no external services needed
• HTTPS support out of the box
• Great for portfolios, demos, and documentation apps

---

✅ Prerequisites

Make sure you have:

• A GitHub account
• Node.js and npm installed
• A React project created using create-react-app
• Git installed and initialized in your project folder

---

🛠️ Step-by-Step: Deploy React App to GitHub Pages

Step 1: Create a GitHub Repository

1. Go to GitHub and create a new public repository (e.g., my-react-app).
2. Do not initialize with a README (we’ll push code from local later).

---

Step 2: Install gh-pages Package

In your project directory:

npm install gh-pages --save-dev

This package will help deploy your app to the gh-pages branch, which GitHub Pages uses to serve static content.

---

Step 3: Add homepage to package.json

In package.json, add the following line (replace with your GitHub username and repo name):

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

Example:

"homepage": "https://johndoe.github.io/my-react-app"

---

Step 4: Add Deploy Scripts

Update your package.json scripts section to include:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

• predeploy will build your app
• deploy will publish the contents of the build directory to the gh-pages branch

---

Step 5: Push Your Code to GitHub

Initialize and push to GitHub:

git init
git remote add origin https://github.com/<your-username>/<repo-name>.git
git add .
git commit -m "Initial commit"
git push -u origin main

---

Step 6: Deploy the App

Run:

npm run deploy

This builds the app and pushes the output to the gh-pages branch.

---

✅ Done! Access Your Live App

Visit:

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

Your React app is now live on GitHub Pages!

---

🧠 Bonus Tips

• Custom Domains: Add a CNAME file in the public/ folder or configure it in your GitHub Pages settings.
• 404 Handling: Create a custom 404.html to handle broken routes.
• Routing Support: For react-router-dom, use hash routing (<HashRouter>) or configure a fallback in GitHub Pages.

---

🧹 To Remove the Deployment

If you want to remove your hosted site:

gh-pages-clean

Or manually delete the gh-pages branch from GitHub.

---

✅ Summary

Step	Action
1	Create a GitHub repository
2	Install gh-pages
3	Add homepage in package.json
4	Add deploy scripts
5	Push code to GitHub
6	Run npm run deploy

---

Conclusion

Deploying a React app to GitHub Pages is fast, free, and incredibly effective for most use cases. With just a few tweaks to your package.json and a single deploy command, your app is available to the world.