DEV Community

Cover image for How to Deploy Your React or Vite Project on GitHub Pages using gh-pages
Tharaka Sandaruwan
Tharaka Sandaruwan

Posted on • Edited on

How to Deploy Your React or Vite Project on GitHub Pages using gh-pages

GitHub Pages provides a simple and free way to host and showcase your web projects. If you’ve built your project using React or Vite, deploying it on GitHub Pages is a straightforward process. In this guide, we’ll walk through the steps of deploying your React or Vite project using the gh-pages library.

Prerequisites
Before you begin, ensure you have the following:

  • GitHub account.
  • A React or Vite project hosted on GitHub.

Step 1: Install gh-pages on your project

Go to your project folder and install the gh-pages package as a dev dependency in your project. Open your terminal and run the following command:

npm i gh-pages --save-dev
Enter fullscreen mode Exit fullscreen mode

For yarn users:

yarn add gh-pages -D
Enter fullscreen mode Exit fullscreen mode

Step 2: Update your package.json

Open your package.json file and update it as follows:

{
  "homepage": "http://<git username>.github.io/<repo name>", // Add this line
  "name": "example",
  // ...Other scripts
  "scripts": {
    // ...Other scripts
    "predeploy": "npm run build", // Add this line
    "deploy": "gh-pages -d <build folder name>"  // Add this line
  }
}
Enter fullscreen mode Exit fullscreen mode

Let’s say your github username is ‘gituser’ and your project hosted repository name is 'repo'. In this case, your package.json is something like this.

package.json file

This configuration sets up the necessary scripts to build your project before deploying it with gh-pages.

If you are using vite Update the vite.config.js as follows before the deployment:

vite.config.js file

Step 3: Deploy Your Project

Now that gh-pages is set up, deploy your project by running the following command:

npm run deploy
Enter fullscreen mode Exit fullscreen mode

For yarn users:

yarn deploy
Enter fullscreen mode Exit fullscreen mode

This command will deploy your build folder into the gh-pages branch in your github repository. You can verify it by navigating your github project repository action tab. It will appear like this. Once deployment is complete, you will see the green tick.

github actions

Step 4: Configure GitHub Pages

  • Go to your GitHub repository.
  • Click on the “Settings” tab.
  • Scroll down to the “GitHub Pages” section.
  • In the “Source” dropdown, select the gh-pages branch.
  • Click “Save.”

Your React / Vite project is now deployed on GitHub Pages! You can access it using the link provided in the “GitHub Pages” section of your repository settings.

Tips and Troubleshooting

  • Custom Domain:
    If you have a custom domain, configure it in the “Custom domain” field in the GitHub Pages settings.

  • 404 Issues:
    If you encounter 404 issues, ensure that your router is configured properly. For React Router, set the basename property in your BrowserRouter.

Conclusion

Deploying your React/Vite project on GitHub Pages using gh-pages is a quick and effective way to showcase your work. By following these simple steps, you can easily share your web applications with the world. Happy coding!

Top comments (3)

Collapse
 
maxprilutskiy profile image
Max Prilutskiy

Good stuff, really useful.

Collapse
 
tharakamts profile image
Tharaka Sandaruwan

Thank you!

Collapse
 
pablofing profile image
Pablo Perdomo

vjbfgtbg5t?
fewnughtr

¿?fvgdhjysdvf?