How to Host React App on GitHub Pages

Hosting a React application on GitHub Pages is one of the most accessible and cost-effective ways to deploy modern web applications. Whether you’re a developer building a personal portfolio, a student showcasing a class project, or a startup testing a prototype, GitHub Pages provides a free, reliable, and scalable platform to publish your React app to the world. Unlike traditional web hosting services that require server configuration, domain purchases, or credit card details, GitHub Pages allows you to deploy directly from your Git repository with minimal setup.

React, being a client-side JavaScript library, generates static files during the build process—HTML, CSS, and JavaScript bundles—that are perfectly suited for static hosting platforms like GitHub Pages. This tutorial walks you through every step required to successfully host your React application on GitHub Pages, from initializing your project to troubleshooting common deployment issues. By the end of this guide, you’ll have a fully functional, live React app accessible via a custom or GitHub-provided URL, optimized for performance and SEO.

Understanding how to deploy React apps to GitHub Pages isn’t just a technical skill—it’s a foundational competency for front-end developers. It enables rapid iteration, easy sharing, and seamless collaboration. Plus, since GitHub Pages integrates directly with your version control workflow, you can automate deployments using GitHub Actions or simply push changes to trigger a rebuild. In this comprehensive guide, we’ll cover everything you need to know to host your React app efficiently and professionally.

Step-by-Step Guide

Prerequisites

Before you begin deploying your React application to GitHub Pages, ensure you have the following:

• A GitHub account (free to create at github.com)
• Node.js and npm (or yarn) installed on your machine
• A React project (created via Create React App, Vite, or another tool)
• Basic familiarity with the command line and Git

If you don’t already have a React project, create one using Create React App by running:

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

This generates a fully configured React application with all necessary dependencies and folder structure.

Step 1: Build Your React Application

React applications are not served directly from source code. Instead, they must be compiled into static files optimized for production. This process is handled by the build command provided by Create React App.

In your project directory, run:

npm run build

This command creates a new folder named build in your project root. Inside this folder, you’ll find:

• index.html — the main entry point of your app
• static/ — contains bundled CSS and JavaScript files
• Other assets like manifest.json, favicon.ico, etc.

The build folder contains everything needed to serve your app statically. These files are ready to be uploaded to GitHub Pages.

Step 2: Configure the Package.json File

GitHub Pages serves content from a specific branch in your repository. By default, it looks for files in the main or master branch, or from a gh-pages branch if configured. However, for React apps, we need to tell the build process where your app will be hosted.

If your GitHub Pages site will be accessible at https://username.github.io (user site), no additional configuration is needed. But if you’re hosting a project site at https://username.github.io/repository-name, you must set the homepage field in your package.json file.

Open package.json and add or update the homepage field:

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

Replace username with your GitHub username and repository-name with the name of your GitHub repository. For example:

"homepage": "https://johnsmith.github.io/my-react-portfolio"

This setting ensures that React’s router (if used) generates correct paths for assets and routes during the build process. Without this, your app may load without styles or scripts, or routing may break entirely.

Step 3: Install gh-pages Package

To automate the deployment process, we’ll use the gh-pages npm package. This tool handles pushing the contents of the build folder to a designated branch on GitHub.

Install it as a development dependency:

npm install gh-pages --save-dev

Step 4: Update Package.json Scripts

Now, add two new scripts to your package.json file under the scripts section:

"scripts": {
"start": "react-scripts start",
"build": "react-scripts build",
"deploy": "gh-pages -d build"
}

The deploy script tells gh-pages to deploy the contents of the build directory to the gh-pages branch on GitHub. This branch will be created automatically if it doesn’t exist.

Step 5: Initialize Git and Commit Your Code

If your project isn’t already a Git repository, initialize it:

git init
git add .
git commit -m "Initial commit"

Then, create a new repository on GitHub. Do not initialize it with a README, .gitignore, or license—those can be added later. Copy the repository URL from GitHub (it will look like https://github.com/username/repository-name.git).

Link your local repository to the remote one:

git remote add origin https://github.com/username/repository-name.git

Push your code to the main branch:

git branch -M main
git push -u origin main

Step 6: Deploy to GitHub Pages

Now that your code is on GitHub, it’s time to deploy the build files:

npm run deploy

This command will:

• Run npm run build to generate the production-ready files
• Create a new branch called gh-pages on your GitHub repository
• Push all files from the build folder into the gh-pages branch
• Output a success message with the live URL

Once complete, you’ll see a message like:

Published: https://username.github.io/repository-name

Step 7: Enable GitHub Pages in Repository Settings

GitHub Pages doesn’t always activate automatically. To ensure your site is live:

1. Go to your repository on GitHub.
2. Click on the Settings tab.
3. In the left sidebar, click Pages.
4. Under Source, select Deploy from a branch.
5. Choose gh-pages as the branch.
6. Click Save.

Within a few moments, GitHub will build and publish your site. You’ll see a green banner confirming that your site is published at the URL listed above.

Step 8: Verify Your Deployment

Open your live URL in a browser:

https://username.github.io/repository-name

If everything is configured correctly, your React app should load without errors. If you see a blank page or 404, double-check:

• That the homepage field in package.json matches your repository name
• That the gh-pages branch exists and contains the build files
• That GitHub Pages is set to use the gh-pages branch
• That you’re not using client-side routing (like React Router) without proper configuration

Best Practices

Use a Custom Domain (Optional but Recommended)

While GitHub Pages provides a free subdomain (username.github.io), using a custom domain like www.yourwebsite.com adds professionalism and brand recognition. To set this up:

1. Purchase a domain from a registrar (e.g., Namecheap, Google Domains).
2. In your repository’s GitHub Pages settings, under Custom domain, enter your domain name.
3. Configure DNS records with your domain provider:
• A record pointing to 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153
• Or a CNAME record pointing to username.github.io (if using a subdomain like app.yourwebsite.com)

4. Wait up to 48 hours for DNS propagation.

GitHub Pages will automatically provision an SSL certificate via Let’s Encrypt, ensuring your site loads securely over HTTPS.

Optimize Build Output

By default, Create React App generates minified and hashed filenames for better caching. However, you can further optimize performance:

• Use react-loadable or React.lazy() for code splitting to reduce initial bundle size.
• Compress images using tools like imagemin or sharp before including them in your app.
• Remove unused dependencies and libraries to reduce bundle size.
• Enable GZIP compression on GitHub Pages (enabled by default for static assets).

Handle Client-Side Routing Correctly

If your React app uses React Router with BrowserRouter, GitHub Pages may return a 404 error when users refresh on nested routes (e.g., /about or /contact).

To fix this, create a file named 404.html in your public folder with the following content:

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>My React App</title>
<script>
window.location.href = window.location.pathname + window.location.search;
</script>
</head>
<body>
<p>Redirecting...</p>
</body>
</html>

This file ensures that any unknown route redirects to index.html, allowing React Router to handle navigation client-side. The 404.html file will be served automatically by GitHub Pages for any unmatched paths.

Enable Caching Headers

GitHub Pages automatically sets caching headers for static assets, but you can improve performance further by ensuring long-term caching for immutable files (e.g., hashed JavaScript and CSS files). React’s build process already does this by appending hashes to filenames, so no additional configuration is needed.

Use Environment Variables for Production

Never commit API keys or secrets to your repository. Use environment variables via .env files:

• .env — for development
• .env.production — for production builds

For example:

REACT_APP_API_URL=https://api.yourdomain.com

Access them in your code using process.env.REACT_APP_API_URL. These variables are embedded into the build at compile time and are safe to deploy publicly.

Monitor Performance and SEO

After deployment, use tools like Google Lighthouse (in Chrome DevTools) to audit your site for performance, accessibility, and SEO. Common improvements include:

• Adding meta tags for title and description in public/index.html
• Using semantic HTML elements
• Optimizing images with loading="lazy"
• Ensuring sufficient color contrast

Tools and Resources

Essential Tools

• Create React App — Official tool for scaffolding React projects with zero configuration.
• gh-pages — npm package that automates deployment to GitHub Pages.
• GitHub CLI — Command-line tool to manage repositories and deployments without leaving your terminal.
• Netlify or Vercel — Alternative static hosts with more advanced features (auto-deploy, custom domains, serverless functions). Useful if GitHub Pages limitations become restrictive.
• Webpack Bundle Analyzer — Visualize bundle sizes to identify large dependencies.
• Google Lighthouse — Built-in Chrome tool for performance, accessibility, and SEO audits.

Documentation and References

• Create React App Deployment Guide
• GitHub Pages Official Documentation
• React Router Documentation
• gh-pages GitHub Repository
• MIME Types for Static Assets

Templates and Starter Kits

To accelerate your deployment process, consider using these pre-configured templates:

• React GitHub Pages Template — GitHub repository with pre-configured package.json and build scripts.
• Vite + GitHub Pages — For users preferring Vite over Create React App, the deployment process is nearly identical.
• React Portfolio Template — A minimal, responsive portfolio template ready for GitHub Pages deployment.

Real Examples

Example 1: Personal Portfolio

Developer Jane Doe created a React portfolio using Create React App and deployed it to GitHub Pages. Her repository is named jane-portfolio, and her GitHub username is janedoe. She configured her package.json as follows:

"homepage": "https://janedoe.github.io/jane-portfolio"

She installed gh-pages, added the deploy script, and ran npm run deploy. After enabling GitHub Pages to use the gh-pages branch, her site went live at:

https://janedoe.github.io/jane-portfolio

She then added a custom domain www.janedoe.dev and configured DNS records. Her site now loads securely at both URLs, with full SEO metadata and Lighthouse scores above 95.

Example 2: Open-Source Project Demo

A team built a React-based dashboard for a public data visualization tool. They hosted it on GitHub Pages under their organization’s repository: https://orgname.github.io/data-dashboard.

To handle routing, they created a 404.html file in the public folder. They also added a robots.txt file to allow search engines to index their content:

User-agent: *
Allow: /

They used GitHub Actions to automatically rebuild and redeploy on every push to the main branch, eliminating manual deployment steps.

Example 3: Student Project Showcase

A university student built a React app for a final project and deployed it using GitHub Pages to share with professors and peers. The app used React Router for navigation. After encountering 404 errors on refresh, she added the 404.html redirect file and resolved the issue immediately.

She also added Open Graph tags to her public/index.html to improve how links appear when shared on social media:

<meta property="og:title" content="My React Project" />
<meta property="og:description" content="A student-built React dashboard for tracking academic progress." />
<meta property="og:image" content="https://username.github.io/repository-name/preview.png" />

FAQs

Why is my React app blank when deployed to GitHub Pages?

The most common cause is an incorrect or missing homepage field in package.json. If your repository is named my-app and your username is user, your homepage must be https://user.github.io/my-app. Without this, asset paths like /static/js/main.js will be requested from the root domain instead of the subpath, resulting in 404s.

Can I use React Router with GitHub Pages?

Yes, but you must configure a 404.html file in your public folder to redirect all routes to index.html. This allows React Router to handle navigation client-side. Without this, refreshing on a route like /about will return a GitHub 404 page.

How long does it take for GitHub Pages to deploy?

Deployment typically takes 1–5 minutes after running npm run deploy. Once the gh-pages branch is updated, GitHub Pages usually publishes the site within 30–60 seconds. If it takes longer than 10 minutes, check your branch settings in Repository → Settings → Pages.

Can I use a custom domain with GitHub Pages for free?

Yes. GitHub Pages provides free SSL certificates for custom domains. You only pay for the domain registration itself (e.g., $10–15/year at Namecheap). GitHub handles the HTTPS certificate provisioning automatically.

What happens if I change my GitHub username?

If you change your GitHub username, your old GitHub Pages URL (oldname.github.io) will no longer work. You’ll need to:

• Update the homepage field in package.json to reflect your new username.
• Re-run npm run deploy.
• Update any links or references to your old URL.

Can I host multiple React apps on one GitHub account?

Yes. You can create one repository per app. For user sites, you can only have one: username.github.io. For project sites, you can have unlimited repositories like username.github.io/project1, username.github.io/project2, etc.

Does GitHub Pages support server-side rendering (SSR)?

No. GitHub Pages is a static hosting service and does not support Node.js servers, APIs, or server-side rendering. If you need SSR, consider platforms like Vercel, Netlify, or AWS Amplify.

How do I update my React app after deployment?

Simply make changes to your code, run npm run build, then run npm run deploy again. The gh-pages branch will be overwritten with the new build files. You can also automate this using GitHub Actions for continuous deployment.

Why am I seeing a 404 on my custom domain?

This usually means your DNS records are misconfigured. Double-check that your A records point to GitHub’s IP addresses or your CNAME record points to username.github.io. It may take up to 48 hours for DNS changes to propagate globally.

Is GitHub Pages suitable for production apps?

GitHub Pages is suitable for static apps, portfolios, documentation, and prototypes. It’s not recommended for high-traffic applications, dynamic content, or apps requiring backend APIs. For production-grade applications with scalability needs, consider Vercel, Netlify, or AWS S3 + CloudFront.

Conclusion

Hosting a React application on GitHub Pages is a straightforward, powerful, and free method to bring your front-end projects to life. With just a few configuration steps—setting the homepage, installing gh-pages, and deploying your build—you can publish a professional, production-ready React app accessible to anyone with a web browser.

This method is ideal for developers seeking to showcase their work, students submitting assignments, or teams launching MVPs without financial overhead. The integration with Git ensures version control, collaboration, and traceability, making it an excellent choice for modern development workflows.

By following the best practices outlined in this guide—configuring routing, optimizing assets, using custom domains, and monitoring performance—you can ensure your deployed React app not only functions correctly but also delivers a fast, secure, and SEO-friendly experience.

As you continue building and deploying applications, remember that GitHub Pages is just one tool in your deployment toolkit. As your needs evolve—toward higher traffic, dynamic content, or serverless functions—you can seamlessly migrate to platforms like Vercel or Netlify without losing your progress. But for now, with this guide, you have everything you need to confidently host your React app on GitHub Pages and share your work with the world.