Deploying a Vite App to GitHub Pages using GitHub Actions: A Step-by-Step Guide



Creating efficient workflows for deploying web applications is crucial in today’s fast-paced development landscape. GitHub Pages and GitHub Actions have emerged as powerful tools for automating the deployment process. This guide aims to walk developers through deploying a Vite.js application to GitHub Pages using GitHub Actions.

By the end of this tutorial, you’ll have a comprehensive understanding of how to set up an automated deployment pipeline for your Vite app.


Before we dive into the deployment process, let’s ensure you have the necessary tools and knowledge:

  1. Vite.js Knowledge: Familiarity with Vite.js, a build tool that significantly enhances the development experience for modern web applications.

  2. GitHub Account: A GitHub account is necessary to create repositories and set up GitHub Actions.

  3. Git: A basic understanding of Git for version control.

  4. Node.js and npm: Ensure you have Node.js and npm (Node Package Manager) installed on your machine.

  5. Vite App: A Vite.js application ready to be deployed.

Project Setup

For this guide, let’s assume you have a Vite app name MyViteApp that you want to deploy to GitHub Pages.

  1. Create a GitHub Repository:

Go to your GitHub account and create a new repository named my-vite-app (or any name you prefer).

Clone the repository to your local machine using git clone.

  1. Setting up the Vite App:

Navigate to your project directory: cd my-vite-app.

Install dependencies: Run npm install to install the necessary packages.

  1. Create a GitHub Action Workflow:

In your repository, create a new directory named .github/workflows. Inside this directory, create a YAML file named deploy.yml. This is where you’ll define your GitHub Actions workflow.

Copy and paste the following code to your deploy.yml file:

# Simple workflow for deploying static content to GitHub Pages

name: Deploy to GitHub Pages


  # Runs on pushes targeting the default branch


    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab


# Sets the GITHUB_TOKEN permissions to allow deployment to GitHub Pages


  contents: read

  pages: write

  id-token: write

# Allow one concurrent deployment


  group: 'pages'

  cancel-in-progress: true


  # Single deploy job since we're just deploying



      name: github-pages

      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest


      - name: Checkout

        uses: actions/checkout@v3

      - name: Set up Node

        uses: actions/setup-node@v3


          node-version: 18

          cache: 'npm'

      - name: Install dependencies

        run: npm install

      - name: Build

        run: npm run build

      - name: Setup Pages

        uses: actions/configure-pages@v3

      - name: Upload artifact

        uses: actions/upload-pages-artifact@v1


          # Upload dist repository

          path: './dist'

      - name: Deploy to GitHub Pages

        id: deployment

        uses: actions/deploy-pages@v1

Configure Vite Config

Add a property called base with the value of our repository name on vite.config.js or vite.config.ts. For example, if our repository name is my-vite-app, then we set the configuration as follows:

// vite.config.js

import { defineConfig } from 'vite'

import react from '@vitejs/plugin-react'


export default defineConfig({

  plugins: [react()],

  base: '/my-vite-app/'


The deployment URL would be https://<OUR_GITHUB_USERNAME>

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

Deploying the App

With the GitHub Actions workflow in place, here’s how the deployment process works:

  1. Make Changes and Push:

Make changes to your Vite app. Commit and push your changes to the main branch.

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

Commit the deployment workflow and push the changes to GitHub.

  1. GitHub Actions Workflow:

GitHub Actions will automatically trigger the workflow defined in deploy.yml on the push event.

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

PermissionDon’t forget to enable the write permission. To fix that, go to Actions Settings, select Read and Write permissions and hit Save:

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


  1. Accessing Deployed App:

Once the workflow completes successfully, your Vite app will be deployed to the GitHub Pages URL you specified in the base field with the value of our repository name on vite.config.js.

Access your deployed app at


Congratulations! You’ve successfully set up an automated deployment pipeline for your Vite.js app using GitHub Actions and deployed it to GitHub Pages. This streamlined workflow will save you time and effort, allowing you to focus on developing amazing web applications.

By following this guide, you’ve gained valuable insights into configuring GitHub Actions, creating a deployment workflow, and utilizing GitHub Pages for hosting your projects. This knowledge will empower you to streamline your development process and efficiently deploy your future web applications.

Thank you for your valuable time!

If you found these helpful, share them with your friends.

Happy coding!

Don’t forget to drop your comment.



I'm a web developer, I have a strong technical background that allows me to understand complex topics and explain them in a clear and concise way.