How to deploy a React app to GitHub Pages
Łukasz Holeczek
Follow Łukasz Holeczek on GitHub
Connect with Łukasz Holeczek on LinkedIn
Follow Łukasz Holeczek on X (Twitter)
GitHub Pages offers free static hosting for React applications, making it an excellent choice for personal projects, documentation sites, and open-source demos.
As the creator of CoreUI with over 12 years of React experience since 2014, I’ve deployed numerous demo applications and documentation sites to GitHub Pages.
Deploying to GitHub Pages requires building your React app and pushing the build folder to a special gh-pages branch.
The gh-pages package automates this process with a single command.
Use the gh-pages package to deploy your React app build to GitHub Pages automatically.
Install gh-pages:
npm install --save-dev gh-pages
Add to package.json:
{
"homepage": "https://yourusername.github.io/repository-name",
"scripts": {
"predeploy": "npm run build",
"deploy": "gh-pages -d build"
}
}
Deploy:
npm run deploy
For Create React App with routing, add to public/404.html:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Redirecting</title>
<script>
sessionStorage.redirect = location.href
</script>
<meta http-equiv="refresh" content="0;URL='/'">
</head>
</html>
Add to public/index.html in <head>:
<script>
(function() {
const redirect = sessionStorage.redirect
delete sessionStorage.redirect
if (redirect && redirect !== location.href) {
history.replaceState(null, null, redirect)
}
})()
</script>
Configure custom domain (optional):
Create public/CNAME file:
yourdomain.com
Then configure DNS records with your domain provider.
Best Practice Note
The homepage field in package.json must match your GitHub Pages URL format. For user/organization sites (username.github.io), use the root URL. For project sites, include the repository name. The gh-pages package creates and pushes to the gh-pages branch automatically. Enable GitHub Pages in repository settings and select the gh-pages branch as source. The 404.html workaround enables client-side routing on GitHub Pages. This is how we host CoreUI demos and documentation—using GitHub Pages for free, reliable hosting with automatic deployments from GitHub Actions.
