Overview

When I wanted to quickly deploy a small React project I had been experimenting with, I considered GitHub Pages. I had used Firebase Hosting and Vercel before, but never GitHub Pages, so I thought it would be a good chance to understand how it works.

While experimenting, I ran into some challenges and realized both the strengths and limitations of GitHub Pages. This helped me clarify when GitHub Pages is useful, and when other platforms like Vercel or Firebase are a better fit.

What I Learned

• GitHub Pages
  GitHub Pages is primarily designed to serve static files. It’s great for quickly publishing projects made up of plain HTML, CSS, and JavaScript. For React, however, you can’t deploy the repository directly — you first need to build it into static assets and then deploy those. When deploying SPAs, you either use a command-line tool (gh-pages) or GitHub Actions to handle the build and deploy steps.
  With client-side routing (e.g., React Router), GitHub Pages always falls back to 404.html for unknown paths. To work around this, you need to copy index.html to 404.html so the React app can boot and handle the route.
• Deploying with Commands
  By installing the gh-pages package, you can deploy to GitHub Pages directly from the command line. This is simple and convenient, but it feels slightly different from the usual development flow of creating a branch, merging into main, and letting deployment happen automatically.
• Deploying with GitHub Actions
  With GitHub Actions, you can automate the build and deploy process. Once configured, pushing to main will trigger the workflow to build and deploy automatically. This approach feels closer to a typical development workflow, where deployment happens at the point of merging changes into the main branch.
  See my deploy.yml workflow on GitHub
• React Configuration
  In vite.config.ts, you need to set the base option to match the repository name. When using React Router, you also need to provide a basename, for example:

  
  <BrowserRouter basename={import.meta.env.BASE_URL}>
    <App />
  </BrowserRouter>
  
  

  This ensures routing works correctly, since GitHub Pages serves the app under a repository-based base path. Additionally, copying index.html to 404.html is necessary to handle unknown paths.
• Routing Considerations
  GitHub Pages only serves static files and does not support server-side routing. For client-side routing (e.g., React Router), unknown paths fall back to 404.html. If 404.html doesn’t exist, the React app cannot boot, and the default GitHub Pages 404 is shown. Copying index.html to 404.html solves this, but it’s a hack — the HTTP status code remains 404, and you’ll still see 404 errors in the console.
  
  For apps that require proper routing, platforms that support rewrite rules (e.g. Vercel, Firebase Hosting) are more suitable.