DEV Community

Cover image for How to Deploy a React + Vite App on GitHub Pages: A Beginner-Friendly Guide 🚀
SUGATA CHAKMA
SUGATA CHAKMA

Posted on AI-assisted

How to Deploy a React + Vite App on GitHub Pages: A Beginner-Friendly Guide 🚀

#webdev #beginners #git #react

Have you built your first React project using Vite and want to share it with the world?

You can deploy your project for free using GitHub Pages. You don't need to purchase hosting or configure a server. With a few configuration changes and some Git commands, you can publish your project online.

In this tutorial, I'll walk you through the complete process of deploying a React + Vite application to GitHub Pages using the gh-pages package.

Whether you're building your first portfolio, landing page, or mini project, this guide is for you!

📌 What You'll Learn

By the end of this tutorial, you'll know how to:

  • Create a GitHub repository for your React project.
  • Push your local project to GitHub using Git.
  • Install and configure the gh-pages package.
  • Update your Vite configuration for GitHub Pages.
  • Deploy your application and troubleshoot common problems.

🛠️ Prerequisites

Before getting started, make sure you have:

If you haven't created your React + Vite project yet, you can start with:

npm create vite@latest my-website -- --template react
cd my-website
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

Open the local URL shown in your terminal to check that your application works.

Let's deploy it!

Step 1: Install the gh-pages Package

First, open your project folder in VS Code.

Open the integrated terminal and run:

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

The gh-pages package helps publish your built website to a branch named gh-pages in your GitHub repository.

We use a production build because GitHub Pages needs the generated website files, not the Vite development server.

Step 2: Create a GitHub Repository

Now we need a GitHub repository to store our project.

  1. Open GitHub.
  2. Click the New repository option.
  3. Enter a repository name, for example, my-website.
  4. Choose Public for this tutorial.
  5. Create the repository.

For the simplest first-time setup, create an empty repository without automatically adding a README, license, or .gitignore file. This avoids an unnecessary Git history conflict when pushing your existing local project.

Keep your GitHub username and repository name available. You'll need them in the next steps.

Step 3: Push Your Project to GitHub

Return to the VS Code terminal and make sure you're inside your React project folder.

If Git has not been initialized in this folder yet, run:

git init
git add .
git commit -m "Initial commit"
git branch -M main
Enter fullscreen mode Exit fullscreen mode

Now connect your local project to your GitHub repository.

Replace YOUR_USERNAME with your GitHub username:

git remote add origin https://github.com/YOUR_USERNAME/my-website.git
git push -u origin main
Enter fullscreen mode Exit fullscreen mode

For example, if your GitHub username is SugataDev, the remote URL would be:

git remote add origin https://github.com/SugataDev/my-website.git
Enter fullscreen mode Exit fullscreen mode

Important: Run git remote add origin only if your project doesn't already have an origin remote. If it does, check it using:

git remote -v
Enter fullscreen mode Exit fullscreen mode

After pushing, refresh your GitHub repository. You should see your React + Vite project files online.

Step 4: Configure the Deployment Scripts

Open your package.json file in VS Code.

Find the existing "scripts" section and add these two scripts:

"predeploy": "npm run build",
"deploy": "gh-pages -d dist"
Enter fullscreen mode Exit fullscreen mode

For a typical Vite project, the scripts section may look like this:

"scripts": {
  "dev": "vite",
  "build": "vite build",
  "lint": "eslint .",
  "preview": "vite preview",
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}
Enter fullscreen mode Exit fullscreen mode

Don't replace your entire package.json file. Keep your existing dependencies and scripts; simply add predeploy and deploy to the scripts object.

Let's understand what these commands do.

  • predeploy automatically runs before the deployment command and builds the application.
  • npm run build generates the production-ready files.
  • dist is the directory where Vite places those files by default.
  • gh-pages -d dist publishes the contents of the dist directory to the gh-pages branch.

This means you don't have to build the project manually every time before deploying. The predeploy script handles that step automatically.

Step 5: Update the Vite Configuration

This is one of the most important steps.

When a Vite application is deployed to a GitHub repository URL, its assets need to use the correct base path. Otherwise, your website might load without its CSS, JavaScript, or images.

Open your vite.config.js file.

For a repository named my-website, configure it like this:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  base: "/my-website/",
});
Enter fullscreen mode Exit fullscreen mode

If your project uses vite.config.ts, make the equivalent change there instead.

Notice this line:

base: "/my-website/",
Enter fullscreen mode Exit fullscreen mode

The value must match your repository name, including the leading and trailing slashes.

For example, if your repository is named portfolio, use:

base: "/portfolio/",
Enter fullscreen mode Exit fullscreen mode

This configuration is appropriate for a project deployed at:

https://YOUR_USERNAME.github.io/my-website/

If you're deploying to a user or organization site at https://YOUR_USERNAME.github.io/, the base path is usually / instead.

You can read more in the official Vite deployment guide.

Step 6: Deploy Your Application

Now everything is ready.

Open the VS Code terminal and run:

npm run deploy
Enter fullscreen mode Exit fullscreen mode

Here's what happens behind the scenes:

  1. The predeploy script runs.
  2. Vite builds the React application.
  3. The production files are created inside the dist directory.
  4. The gh-pages package publishes those files to the gh-pages branch.

Wait for the command to finish successfully. You should see a message indicating that the content has been published.

If you encounter an error, read the terminal output carefully before continuing.

Step 7: Enable GitHub Pages

Now go back to your repository on GitHub.

Follow these steps:

  1. Open your repository.
  2. Click Settings.
  3. Navigate to Pages in the sidebar.
  4. Under Build and deployment, set the source to Deploy from a branch.
  5. Choose gh-pages as the publishing branch.
  6. Select /(root) as the folder.
  7. Click Save.

Make sure you select the gh-pages branch, not main, because the deployment command published the built website to gh-pages.

GitHub Pages will then publish the website. You can monitor deployment activity in the repository's Actions tab.

For more details, see the official GitHub Pages documentation.

Step 8: Visit Your Live Website 🎉

After GitHub finishes publishing your site, open the Pages section in your repository settings.

GitHub should display your website URL. For this example, it will look like:

https://YOUR_USERNAME.github.io/my-website/

Open the link in your browser.

Congratulations! Your React + Vite project is now available online.

You can share this URL with friends, include it in your portfolio, or add it to your GitHub profile.

🔄 How to Update Your Website Later

One of the best parts of this workflow is that you can deploy future changes with the same command.

First, edit your project and test it locally:

npm run dev
Enter fullscreen mode Exit fullscreen mode

Then commit and push your source-code changes:

git add .
git commit -m "Update website"
git push origin main
Enter fullscreen mode Exit fullscreen mode

Finally, publish the updated production build:

npm run deploy
Enter fullscreen mode Exit fullscreen mode

The deployment command builds the latest version and updates the gh-pages branch.

Remember that pushing to main alone does not automatically run this particular gh-pages deployment setup. You need to run npm run deploy unless you configure a separate automated workflow.

🐛 Common GitHub Pages Deployment Problems

Let's look at a few problems you might encounter during deployment.

1. My website is blank

A blank page can happen when asset paths are incorrect.

Solution: Check the base property in vite.config.js. For a repository named my-website, it should be:

base: "/my-website/",
Enter fullscreen mode Exit fullscreen mode

Then deploy again:

npm run deploy
Enter fullscreen mode Exit fullscreen mode

2. CSS, JavaScript, or images are not loading

This may happen when your assets are being requested from the wrong URL.

Solution: Verify your Vite base path and use appropriate asset references. Check your browser's Developer Tools console and Network tab for 404 errors.

3. The GitHub Pages link returns a 404 error

Check that the correct branch and folder are selected in Settings → Pages.

For this tutorial, the source should be:

  • Branch: gh-pages
  • Folder: /(root)

Also, confirm that the deployment command completed successfully and that the gh-pages branch exists.

4. I get an error when adding the remote repository

If Git says that origin already exists, you don't need to add it again.

Check the current remote:

git remote -v
Enter fullscreen mode Exit fullscreen mode

If it points to the wrong repository, update it using:

git remote set-url origin https://github.com/YOUR_USERNAME/my-website.git
Enter fullscreen mode Exit fullscreen mode

Then try pushing again.

5. My website works on the homepage but not on refreshed routes

If you're using React Router, directly refreshing a nested route may return a 404 because GitHub Pages is static hosting.

You may need a routing fallback or a different routing strategy. For simple projects, consider using HashRouter. For more complex applications, review your routing and hosting requirements before deployment.

⚡ Bonus Tip: GitHub Pages Is Not the Only Option

GitHub Pages is an excellent choice for static websites, portfolios, and small front-end projects.

You can also deploy React + Vite projects through services such as Vercel, which can build and deploy your application directly from a connected GitHub repository.

Vite's official deployment guide also describes a GitHub Actions workflow approach, which is useful when you want deployment to happen automatically whenever you push changes to your main branch.

The right hosting platform depends on your project's needs.

✅ Final Thoughts

Deploying a React + Vite project for the first time might seem difficult, but the process becomes much easier once you understand each step.

The basic workflow is:

Create a GitHub repository → Push your code → Install gh-pages → Configure Vite → Run npm run deploy → Enable GitHub Pages.

That's it! Your local React project can now become a live website that anyone can visit.

If you're learning React, try deploying one of your mini projects first. It's a practical way to improve your Git, GitHub, and deployment skills while building your portfolio.

Have you deployed a React project to GitHub Pages before? Share your experience or any deployment problems in the comments. Let's learn together!

🔗 Useful Resources

Top comments (0)