Have you ever finished a side project — maybe a cool React app, a static website, or a portfolio — and then asked yourself, "Now what? How do I put this live?"

One of the easiest (and free!) solutions is GitHub Pages.

In this article, we'll dive into why you'd use gh-pages, how to set it up, and step-by-step how to deploy your project.

Let's get into it! 🎯

📌 The Problem: You Have a Project but No Hosting

When you build a frontend project locally, it's just on your computer. To show it to the world (or a recruiter 👀), you need to host it somewhere.

Traditional hosting options (Netlify, Vercel, AWS) are great but can be overkill for small projects.

GitHub Pages is a perfect alternative:

  • It's free.
  • It's simple to configure.
  • It integrates directly with your GitHub repositories.
  • No backend server needed!

However, manually setting up your project for GitHub Pages (especially for React or Vite apps) can be a pain — because you often need a build process and a specific branch (gh-pages) to host your compiled code.

That's where the gh-pages package comes in!

🛠️ The Method: Use the gh-pages npm package

gh-pages automates the deployment for you:

  • Builds your project.
  • Creates a special gh-pages branch.
  • Pushes your built files there.
  • GitHub then serves it live!

Here's how you can set it up:

⚙️ Step-by-Step Setup Guide

1. Install gh-pages

First, you need to add gh-pages as a development dependency:

npm install gh-pages --save-dev

This allows you to run deployment commands easily.

2. Add a homepage field in your package.json

GitHub Pages needs to know where your app will live.

Open your package.json and add the following at the top level:

"homepage": "https://.github.io/"

For example:

"homepage": "https://johndoe.github.io/my-portfolio"

👉 This ensures that your assets and routes are correctly handled.

3. Update your scripts in package.json

Still in package.json, under the "scripts" section, add:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}
  • predeploy will automatically build your project before deploying.
  • deploy will push the build folder contents to the gh-pages branch.

Note: If you are using Vite, your output folder might be dist instead of build. Adjust accordingly!

4. Push Your Project to GitHub

If you haven't already initialized a Git repo, do:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com//.git
git push -u origin main

This ensures GitHub knows about your project and can host it.

5. Deploy!

Now the fun part 🎉

Run:

npm run deploy

This command:

  • Runs your build process.
  • Pushes the compiled files to the gh-pages branch.
  • Automatically sets up the deployment.

6. Check GitHub Pages Settings (Optional)

  • Go to your repository on GitHub.
  • Navigate to Settings → Pages.
  • Under "Source," select the gh-pages branch.
  • GitHub will display the URL where your site is live.

Boom! 🚀 Your project is now live and shareable with the world.

🧩 Common Gotchas

  • Wrong homepage URL: Always use the format https://.github.io/.
  • 404 errors on refresh (React Router): GitHub Pages doesn't handle client-side routing very well out-of-the-box. You might need to create a 404.html redirect file or adjust your BrowserRouter to HashRouter.
  • Wrong output directory: If you use tools like Vite, make sure to deploy the correct folder (dist, not build).

📚 Final Thoughts

Deploying projects shouldn't be harder than building them!

Thanks to tools like gh-pages, sharing your work becomes effortless.

Now you have no excuse — deploy that project!

Share it, put it in your portfolio, apply for that job, and show off what you made.

🚀 Bonus Tip: Automate Deployments

You can even set up GitHub Actions to auto-deploy every time you push to main. But that's a story for another article... 👀

Thanks for reading!

If you liked this tutorial, drop a ❤️ or comment below — I'd love to see what you deployed!