How to Host a React App on GitHub?

Hosting your React application on GitHub is a quick and efficient way to make your project accessible to the world. GitHub Pages provides free hosting for static websites, which makes it an excellent choice for deploying your React app.

This post will walk you through the process of hosting your React app on GitHub, from setting up your repository to accessing your live site.

Why Host Your React App on GitHub?

• Free Hosting: GitHub Pages allows you to host public projects for free.
• Ease of Deployment: With a few commands, you can have your React app live in minutes.
• Version Control: Your app’s code and deployment history are managed in one place.
• Custom Domains: GitHub Pages supports custom domain integration.

---

Prerequisites

Before you start, ensure you have:

1. Node.js and npm installed: React apps require Node.js and npm for building the project.
2. Git installed: For version control and pushing code to GitHub.
3. A GitHub account: To host your code and deploy the app.
4. React app ready: Create one using create-react-app or your preferred setup.

---

Step 1: Prepare Your React App for Deployment

1. Build the React App

React apps need to be built into static files before deployment. Run the following command in your project directory:
“`bash
npm run build

This command creates a `build/` directory containing the static files required to host your app.  

#### **2. Test the Build Locally (Optional)**  
To ensure the build works as expected, you can serve it locally:  

bash
npx serve -s build

Visit `http://localhost:5000` in your browser to preview the production build.  

---

### **Step 2: Create a GitHub Repository**  

1. **Log in to GitHub**.  
2. **Create a new repository**:  
   - Go to the **Repositories** tab and click **New**.  
   - Name your repository (e.g., `react-app`).  
   - Leave it public (required for GitHub Pages) and do not initialize it with a README (optional).  
3. **Clone the repository** to your local machine:  

bash
git clone https://github.com//.git

---

### **Step 3: Install the `gh-pages` Package**  

GitHub Pages works seamlessly with React apps using the `gh-pages` package. Install it as a development dependency:  

bash
npm install gh-pages –save-dev

---

### **Step 4: Configure Your React App**  

#### **1. Add the `homepage` Property**  
In your React app’s `package.json` file, add the following line:  

json
“homepage”: “https://.github.io/”

Replace `<username>` with your GitHub username and `<repository-name>` with the name of your repository.  

#### **2. Update `scripts` in `package.json`**  
Modify the `scripts` section to include deploy commands:  

json
“scripts”: {
“predeploy”: “npm run build”,
“deploy”: “gh-pages -d build”,
…
}

- **`predeploy`**: Builds the app before deployment.  
- **`deploy`**: Deploys the `build/` directory to GitHub Pages.  

---

### **Step 5: Deploy the React App**  

1. **Push Your Code to GitHub**  
   Add your React app files to the GitHub repository:  

bash
git add .
git commit -m “Initial commit”
git push origin main

2. **Deploy Using `gh-pages`**  
   Run the deploy script to publish your app:  

bash
npm run deploy
“`

This command pushes the contents of the build/ directory to a branch called gh-pages on GitHub.

---

Step 6: Access Your Live Site

Once the deployment completes, GitHub Pages generates a live URL for your app:

• URL format: https://<username>.github.io/<repository-name>/

Your app should now be live!

---

Step 7: Optional Configurations

Custom Domain

To use a custom domain, create a CNAME file in the public/ directory of your React project and add your domain name (e.g., www.example.com).

Configure Branch in GitHub Pages Settings

If the deployment does not work automatically, go to the Settings > Pages section in your GitHub repository. Ensure the gh-pages branch is selected as the source for GitHub Pages.

---

Common Issues and Troubleshooting

1. Blank Page After Deployment

• Ensure the homepage property in package.json is correctly set.
• Verify the build directory structure; asset paths might need adjustments.

2. Deployment Fails

• Check for typos in the deploy script or incorrect permissions.
• Ensure the gh-pages package is installed correctly.

3. Custom Domain Not Working

• Verify DNS settings with your domain registrar.
• Ensure the CNAME file is present in the build/ directory after deployment.

---

Best Practices for Hosting React Apps on GitHub

1. Keep Builds Updated: Re-deploy after every major update to reflect changes.
2. Use Version Control: Always track your source code changes in the main branch.
3. Optimize Performance: Minify CSS/JS and use lazy loading for faster loading times.
4. Test Before Deploying: Always preview your build locally to catch issues early.

---

Conclusion

Hosting a React app on GitHub is a simple and effective way to showcase your project or build a personal portfolio. By following this guide, you can have your app live on the web in just a few steps. Whether you’re building a personal project or deploying documentation for a tool, GitHub Pages makes hosting seamless and accessible.