Deploy Vite to GitHub Pages

01 Apr 2026

2 min read

Vite
GitHub Pages
GitHub Actions
Deployment

Deploying a Vite project to GitHub Pages is straightforward once you have the right configuration. This guide walks you through setting up automatic deployment with GitHub Actions.

Configure Vite for GitHub Pages

The key is setting the correct base path in your Vite config. GitHub Pages serves your site from https://<username>.github.io/<repository-name>/, so your assets need to be prefixed accordingly.

code

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react"; // or vue(), etc.

export default defineConfig({
  plugins: [react()], // or your framework plugin
  base: "/<YOUR_REPOSITORY_NAME>/", // <-- Add this line! Replace <YOUR_REPOSITORY_NAME>
});

Create a GitHub Repository and Push Your Code

If you haven't already, set up your repository and push your code:

Create a new repository on GitHub
Initialize Git in your local project folder (git init)
Add the GitHub repository as a remote (git remote add origin <your-repo-url>)
Stage, commit, and push your initial project code (including the updated vite.config.js) to the main (or master) branch

code

git add .
git commit -m "Initial commit with Vite setup"
git push -u origin main

Set Up GitHub Actions for Automatic Deployment

This method automatically builds and deploys your site whenever you push changes to your main branch.

Create the Workflow

Create the workflow directory: In your project root, create a folder path .github/workflows/
Create a workflow file: Inside .github/workflows/, create a new file named deploy.yml (or any other .yml name)
Paste the following workflow configuration into deploy.yml:

.github/workflows/deploy.ymlcode

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch (usually main or master)
  push:
    branches: ["main"] # Or ['master'] depending on your default branch

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4 # Checks out your repository code

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22 # Use a Node.js version compatible with your project
          cache: "npm" # Or 'yarn', 'pnpm'

      - name: Install dependencies
        run: npm install # Or yarn install, pnpm install

      - name: Build
        # Make sure the base path in vite.config.js is correct!
        run: npm run build # Or yarn build, pnpm build

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

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload the output directory from the build step
          path: "./dist" # Vite's default output directory is 'dist'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Commit and Push the Workflow File

code

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow for deployment"
git push origin main

Configure GitHub Pages Settings

Go to your GitHub repository on the web
Click on the "Settings" tab
In the left sidebar, click on "Pages"
Under "Build and deployment":
- For "Source", select "GitHub Actions" (This option should appear automatically once your workflow runs successfully for the first time after pushing the .yml file)

Verify Deployment

Go to the "Actions" tab in your GitHub repository. You should see the workflow running (or completed) after you pushed the deploy.yml file or pushed new code to main
Once the workflow completes successfully, go back to Settings → Pages
GitHub Pages will display the URL where your site is published (e.g., https://<username>.github.io/<repository-name>/)
It might take a minute or two for the site to become live after the first deployment

Summary

With this setup, every push to main will automatically build your Vite project and deploy it to GitHub Pages. No manual build steps required. Just push and your site updates.

Blogs

Deploy Vite to GitHub Pages

01 Apr 2026

2 min read

Vite
GitHub Pages
GitHub Actions
Deployment

Deploying a Vite project to GitHub Pages is straightforward once you have the right configuration. This guide walks you through setting up automatic deployment with GitHub Actions.

Configure Vite for GitHub Pages

The key is setting the correct base path in your Vite config. GitHub Pages serves your site from https://<username>.github.io/<repository-name>/, so your assets need to be prefixed accordingly.

code

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react"; // or vue(), etc.

export default defineConfig({
  plugins: [react()], // or your framework plugin
  base: "/<YOUR_REPOSITORY_NAME>/", // <-- Add this line! Replace <YOUR_REPOSITORY_NAME>
});

Create a GitHub Repository and Push Your Code

If you haven't already, set up your repository and push your code:

Create a new repository on GitHub
Initialize Git in your local project folder (git init)
Add the GitHub repository as a remote (git remote add origin <your-repo-url>)
Stage, commit, and push your initial project code (including the updated vite.config.js) to the main (or master) branch

code

git add .
git commit -m "Initial commit with Vite setup"
git push -u origin main

Set Up GitHub Actions for Automatic Deployment

This method automatically builds and deploys your site whenever you push changes to your main branch.

Create the Workflow

Create the workflow directory: In your project root, create a folder path .github/workflows/
Create a workflow file: Inside .github/workflows/, create a new file named deploy.yml (or any other .yml name)
Paste the following workflow configuration into deploy.yml:

.github/workflows/deploy.ymlcode

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch (usually main or master)
  push:
    branches: ["main"] # Or ['master'] depending on your default branch

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

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4 # Checks out your repository code

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22 # Use a Node.js version compatible with your project
          cache: "npm" # Or 'yarn', 'pnpm'

      - name: Install dependencies
        run: npm install # Or yarn install, pnpm install

      - name: Build
        # Make sure the base path in vite.config.js is correct!
        run: npm run build # Or yarn build, pnpm build

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

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload the output directory from the build step
          path: "./dist" # Vite's default output directory is 'dist'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Commit and Push the Workflow File

code

git add .github/workflows/deploy.yml
git commit -m "Add GitHub Actions workflow for deployment"
git push origin main

Configure GitHub Pages Settings

Go to your GitHub repository on the web
Click on the "Settings" tab
In the left sidebar, click on "Pages"
Under "Build and deployment":
- For "Source", select "GitHub Actions" (This option should appear automatically once your workflow runs successfully for the first time after pushing the .yml file)

Verify Deployment

Go to the "Actions" tab in your GitHub repository. You should see the workflow running (or completed) after you pushed the deploy.yml file or pushed new code to main
Once the workflow completes successfully, go back to Settings → Pages
GitHub Pages will display the URL where your site is published (e.g., https://<username>.github.io/<repository-name>/)
It might take a minute or two for the site to become live after the first deployment

Summary

With this setup, every push to main will automatically build your Vite project and deploy it to GitHub Pages. No manual build steps required. Just push and your site updates.