DEV Community

Cover image for How to Deploy a React + Vite Project to GitHub Pages and Vercel (Beginner-Friendly Guide)
SUGATA CHAKMA
SUGATA CHAKMA

Posted on

How to Deploy a React + Vite Project to GitHub Pages and Vercel (Beginner-Friendly Guide)

#react #vite #github #webdev

If you're learning React, building your first project is only half the journey. The next step is deploying it so other people can access your website through a live URL.

In this guide, I'll explain how to deploy a React + Vite project to both GitHub Pages and Vercel using VS Code, Git, and GitHub Actions.

Whether you're building a portfolio, a landing page, or a small web application, this guide will help you get started.

🚀 What We'll Learn

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

  • Upload a React project to GitHub.
  • Configure Vite for deployment.
  • Deploy a website using GitHub Pages.
  • Deploy the same project using Vercel.
  • Automatically update your website when you push new code.
  • Troubleshoot common deployment errors.

🛠️ Prerequisites

Before getting started, make sure you have installed:

You should also have a React project created with Vite.

Step 1: Create a React + Vite Project

If you don't already have a project, open your terminal and run:

npm create vite@latest my-react-app -- --template react
Enter fullscreen mode Exit fullscreen mode

Navigate into the project directory:

cd my-react-app
Enter fullscreen mode Exit fullscreen mode

Install the dependencies:

npm install
Enter fullscreen mode Exit fullscreen mode

Start the development server:

npm run dev
Enter fullscreen mode Exit fullscreen mode

Open the local URL shown in your terminal, usually http://localhost:5173/.

If everything works correctly, you're ready to deploy!

Step 2: Upload Your Project to GitHub

First, create a new repository on GitHub.

  1. Open GitHub.
  2. Click New repository.
  3. Name it my-react-app.
  4. Create the repository.

Now open your project in VS Code and run:

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

Connect your local project to your GitHub repository:

git remote add origin https://github.com/YOUR-USERNAME/my-react-app.git
Enter fullscreen mode Exit fullscreen mode

Replace YOUR-USERNAME with your GitHub username.

Push your code:

git push -u origin main
Enter fullscreen mode Exit fullscreen mode

Your project should now appear on GitHub.

Tip: Never commit secrets, API keys, or your .env file to a public repository. Make sure your .gitignore excludes sensitive files.

Step 3: Configure Vite for GitHub Pages

GitHub Pages usually serves project websites from a repository-specific path, such as:

https://YOUR-USERNAME.github.io/my-react-app/

Vercel, on the other hand, normally serves your project from the root of its assigned domain.

To support both platforms, open vite.config.js and configure the base path:

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

export default defineConfig({
  plugins: [react()],
  base: process.env.GITHUB_ACTIONS
    ? '/my-react-app/'
    : '/',
})
Enter fullscreen mode Exit fullscreen mode

Replace my-react-app with your actual GitHub repository name.

This configuration uses the repository path during GitHub Actions builds and / for local development and Vercel builds.

If your existing Vite configuration contains additional plugins or settings, keep them.

Step 4: Deploy to GitHub Pages Using GitHub Actions

GitHub Pages can host static websites for free. With GitHub Actions, you can automate the build and deployment process.

Create the workflow file

Inside your project, create this directory and file:

.github/workflows/deploy.yml
Enter fullscreen mode Exit fullscreen mode

Add the following workflow:

name: Deploy React App to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build project
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload build output
        uses: actions/upload-pages-artifact@v4
        with:
          path: dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    needs: build

    steps:
      - name: Deploy
        id: deployment
        uses: actions/deploy-pages@v4
Enter fullscreen mode Exit fullscreen mode

This workflow builds your React project and publishes the generated dist folder.

Important: This example assumes your project uses npm and has a committed package-lock.json file.

Enable GitHub Pages

Next:

  1. Open your GitHub repository.
  2. Go to Settings → Pages.
  3. Under Build and deployment, select GitHub Actions as the source.

Push the workflow file to GitHub:

git add .
git commit -m "Configure GitHub Pages deployment"
git push
Enter fullscreen mode Exit fullscreen mode

Open the Actions tab and wait for the workflow to finish successfully.

Your website should be available at:

https://YOUR-USERNAME.github.io/my-react-app/

The first deployment may take a few minutes.

Step 5: Deploy the Same Project to Vercel

Vercel is another excellent option for React applications. One of its biggest advantages is automatic deployment whenever you push changes to your connected GitHub repository.

Import your repository

  1. Visit Vercel.
  2. Sign in with your GitHub account.
  3. Click Add New → Project.
  4. Import your my-react-app repository.

Check the project settings:

Setting Value
Framework Preset Vite
Root Directory ./
Build Command npm run build
Output Directory dist

Keep the default install command if Vercel detects your package manager correctly.

Click Deploy and wait for the build to finish.

Vercel will provide a public URL similar to:

https://my-react-app.vercel.app

Your actual URL may be different.

That's it! Your React application is now deployed on Vercel.

Step 6: Update Both Websites Automatically

One of the best parts of this setup is that you don't need to upload your files manually every time you make a change.

After editing your code in VS Code, run:

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

Once you push your changes:

  • GitHub Actions rebuilds and deploys the GitHub Pages version.
  • Vercel detects the push and creates a new deployment.

You can check the status of both deployments from their respective dashboards.

Step 7: Fix Common Deployment Errors

Here are some problems beginners often encounter.

1. My GitHub Pages website shows a blank screen

Possible cause: An incorrect Vite base path.

Check that your repository name matches the path in vite.config.js:

base: process.env.GITHUB_ACTIONS
  ? '/my-react-app/'
  : '/',
Enter fullscreen mode Exit fullscreen mode

Also check the browser console for missing JavaScript or CSS files.

2. GitHub Actions fails at npm ci

This usually means your lockfile is missing or doesn't match your dependencies.

Run locally:

npm install
npm run build
Enter fullscreen mode Exit fullscreen mode

Commit the updated lockfile:

git add package.json package-lock.json
git commit -m "Update dependencies"
git push
Enter fullscreen mode Exit fullscreen mode

3. My Vercel deployment fails

Open the failed deployment in Vercel and inspect its build logs.

Check the following:

  • Is the root directory correct?
  • Does npm run build work locally?
  • Is the output directory set to dist?
  • Are all required dependencies listed in package.json?

4. My website doesn't show the latest changes

First, confirm that the latest deployment succeeded.

Then hard-refresh the browser using Ctrl + Shift + R.

If the problem continues, inspect the latest deployment logs and verify that the correct GitHub branch is connected.

5. My React Router page returns a 404

If your application uses BrowserRouter, refreshing a nested route can fail when the host doesn't redirect unknown paths to index.html.

Vercel can handle this with an SPA fallback rewrite. GitHub Pages requires a different approach, such as hash-based routing or an appropriate fallback strategy.

GitHub Pages vs. Vercel: Which Should You Choose?

Both platforms can host a static React + Vite project, but they have different strengths.

Feature GitHub Pages Vercel
Free static hosting Yes Yes
Custom domain Yes Yes
Automatic deployment With GitHub Actions Built in with Git integration
Build configuration GitHub Actions workflow Project settings
Best suited for Static sites and learning CI/CD React apps and streamlined deployments

For beginners, I recommend using Vercel as your primary hosting platform because setup and ongoing deployments are straightforward.

GitHub Pages is also worth learning because it helps you understand GitHub Actions and deployment workflows.

Remember that GitHub Pages is for static sites. A full MERN application that requires an Express backend and MongoDB needs separate backend and database hosting.

Final Thoughts

Deploying a React + Vite project is an important step in becoming a frontend developer.

You don't need complicated infrastructure to publish your first application. With GitHub, GitHub Pages, and Vercel, you can manage your source code and publish a working website using tools you'll use in real development projects.

Start small, learn the deployment process, and keep improving your projects.

Now it's your turn! Have you deployed a React project before? Which platform do you prefer: GitHub Pages or Vercel?

Share your experience in the comments!

Useful Resources

React #Vite #GitHub #Vercel #WebDevelopment #Beginners

Top comments (1)

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