How to Deploy a Vite React App to GitHub Pages – Step-by-Step Guide

Deploy Vite React App to GitHub Pages

MAR 25, 2025

•

react

vite

github

git

•

2 mins read

Create a New Project

Let’s start by scaffolding a new React project using Vite:

Copy

npm create vite@latest

Once the project is scaffolded, navigate to the project directory and install dependencies:

Copy

cd vite-react-deploy

npm install

Create a GitHub Repository

Initialize Git, commit all the files, and push them to your new repository:

Copy

git init

git add -A

git commit -m "first commit"

git branch -M main

git remote add origin https://github.com/[username]/[repo_name].git # Replace with your username and repo URL

git push -u origin main

Your project is now successfully pushed to GitHub.

Set Base Path in vite.config.ts

If you skip this step, you'll get a 404 error for each asset in your project.

Edit vite.config.ts as follows:

Copy

import { defineConfig } from "vite";

import react from "@vitejs/plugin-react";

export default defineConfig({

plugins: [react()],

base: "/vite-react-deploy/", // Replace with your repo name

});

Add a GitHub Workflow

Create a deploy.yml file inside the .github/workflows directory and add the following content:

Copy

name: Deploy

on:

push:

branches:

- main

jobs:

build:

name: Build

runs-on: ubuntu-latest

steps:

  - name: Checkout repo

    uses: actions/checkout@v4  # Updated to latest version



  - name: Setup Node

    uses: actions/setup-node@v4  # Updated to latest version



  - name: Install dependencies

    uses: bahmutov/npm-install@v1



  - name: Build project

    run: npm run build



  - name: Upload production-ready build files

    uses: actions/upload-artifact@v4  # Updated to v4

    with:

      name: production-files

      path: ./dist

deploy:

name: Deploy

needs: build

runs-on: ubuntu-latest

if: github.ref == 'refs/heads/main'

steps:

  - name: Download artifact

    uses: actions/download-artifact@v4  # Updated to v4

    with:

      name: production-files

      path: ./dist



  - name: Deploy to GitHub Pages

    uses: peaceiris/actions-gh-pages@v4

    with:

      github_token: ${{ secrets.GITHUB_TOKEN }}

      publish_dir: ./dist

Push the workflow changes:

Copy

git add -A

git commit -m "deploy config"

git push

Configure GitHub Actions Permissions

Go to Settings → Actions → General.

Scroll down to Workflow Permissions.

Choose Read and Write and save.

Re-run failed actions if needed.

Configure GitHub Pages

Navigate to Settings → Pages.

Under Source, choose Deploy from branch.

Select the gh-pages branch.

Click Save.

Once the workflow finishes successfully, you’ll see a new deployment on GitHub Pages. Click the link to access your deployed Vite React application!

🚀 Congratulations! Your Vite React App is live!