DEV Community

Cover image for πŸš€ Deploy Your Project to GitHub Pages Using gh-pages
Rohan T George
Rohan T George

Posted on

πŸš€ Deploy Your Project to GitHub Pages Using gh-pages

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
Enter fullscreen mode Exit fullscreen mode

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://<your-github-username>.github.io/<your-repo-name>"
Enter fullscreen mode Exit fullscreen mode

For example:

"homepage": "https://johndoe.github.io/my-portfolio"
Enter fullscreen mode Exit fullscreen mode

πŸ‘‰ 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"
}
Enter fullscreen mode Exit fullscreen mode
  • 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/<your-username>/<your-repo-name>.git
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

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


5. Deploy!

Now the fun part πŸŽ‰

Run:

npm run deploy
Enter fullscreen mode Exit fullscreen mode

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://<username>.github.io/<repo-name>.
  • 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!

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.