Deploy Vite app to GitHub Pages using GitHub Actions

Video tutorial

Screen Shot 2022-05-15 at 18 03 44

Step-by-step instructions

Scaffold a new Vite app and init git

# Create new Vite project using React template
npm create [email protected] React-portfolio4  -- --template react
# Install dependencies and start development server
cd React-portfolio4 
npm install
npm run dev

If the project is working fine, let’s init a new git repository.

git init
git add .
git commit -m "init vite project"

Create a new GitHub repository

Go to and create a new repository.

❗️ Make sure Public is selected if you don’t have a premium account. Otherwise, you won’t be able to host your app using GitHub pages. Screen Shot 2022-05-15 at 16 19 34

Once the repo is created, copy and paste the instructions similar to these to your terminal

git remote add origin [email protected]:sitek94/vite-deploy-demo.git
git branch -M main
git push -u origin main

Create deployment workflow

Create a new file: .github/workflows/deploy.yml and paste the following code:

name: Deploy
      - main
    name: Build
    runs-on: ubuntu-latest
      - name: Checkout repo
        uses: actions/[email protected]
      - name: Setup Node
        uses: actions/[email protected]
          node-version: 16
      - name: Install dependencies
        uses: bahmutov/[email protected]
      - name: Build project
        run: npm run build
      - name: Upload production-ready build files
        uses: actions/[email protected]
          name: production-files
          path: ./dist
    name: Deploy
    needs: build
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
      - name: Download artifact
        uses: actions/[email protected]
          name: production-files
          path: ./dist
      - name: Deploy to GitHub Pages
        uses: peaceiris/[email protected]
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

This workflow will run on every push to the main branch. It will first build the project, and then deploy it to GitHub pages.

Test deployment workflow

Commit deployment workflow and push the changes to GitHub.

git add .
git commit -m "add deploy workflow"
git push

When you go, to Actions and click on the recent workflow, you should see that it failed, because of missing permissions:

Screen Shot 2022-05-15 at 16 33 13

Ensure Actions have write permission

To fix that, go to Actions Settings, select Read and write permissions and hit Save:

Screen Shot 2022-05-15 at 16 35 37

Basically, our action is going to modify the repo, so it needs the write permission.

Go back to Actions, click on failed workflow and in the top-right corner click on Re-run failed jobs

Screen Shot 2022-05-15 at 16 41 29

After job run, you should be able to see a new branch gh-pages created in your repository.

Screen Shot 2022-05-15 at 16 43 26

Enable GitHub pages

To host the app, go to Pages Settings, set Source to gh-pages, and hit Save.

Screen Shot 2022-05-15 at 16 47 07

After a while your app should be deployed and be available at the link displayed in Pages Settings. If you want to follow the deployment process, go to Actions and pages-build-deployment workflow:

Screen Shot 2022-05-15 at 17 07 16

Once deployment is done, visit the app at: https://<YOUR_GITHUB_USER>

Fix assets links

You will see that something is not right, because instead of there is a blank screen. When you inspect it, you will see that some files were not found.

Screen Shot 2022-05-15 at 17 11 42

This is happening, because of the subdirectory-like URL structure GitHub uses for Project Pages. Asset links are referencing the files in the domain root, whereas our project is located in <ROOT>/vite-deploy/demo. This is how the links should look like:

❌ Bad
✅ Good

Fortunately, there is a very easy fix for this. Add the following line in vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
   plugins: [react()],
+  base: '/vite-deploy-demo/'

Now, asset links will have a correct path, so commit the changes, push the code, wait for the deploy to finish and see it for yourself!


Screen Shot 2022-05-15 at 17 31 23



View Github