One of the coolest feature from GitHub is GitHub Pages where we can deploy a simple static site for free. Good use cases for demo, side-projects, portfolios, personal websites, blog, etc. This article will list down the steps to provision a GitHub repo (Vite project) to GitHub pages using GitHub actions.

Changing Vite’s base directory

As GitHub pages are hosted on a subdirectory, for example https://{username}.github.com.io/{repository}, we would need to instruct ViteJS to have its base directory pointing to /{repository}. So in order to do that we issue this command when we build our project.

vite build --base=/repo-name

where repo-name is the name of your GitHub repository.

For convenience, we put it in package.json as a script

{
  "scripts": {
   ...
    "build:github-pages": "vite build --base=/repo-name"
  },
  ...
}

When using client side routing

If our project is using client-side routing, for example vue-router, then we have to use the hash mode to make it work as we are hosting our web app in a subdirectory in GitHub pages.

Updating URLs that access assets in `public` folder

In our project where we use fetch for example to access assets in the public folder, we would need to prefix with the helpful Vite’s environment variable: import.meta.env.BASE_URL. So it might look like this `${import.meta.env.BASE_URL}/sample.txt`.

Setting up GitHub Pages in GitHub

In the repository page (eg: https://github.com/{username}/{repository}), follow the following steps:

Settings
Pages (left hand side)
in Source dropdown > select GitHub Actions
“create your own”
copy and paste the following yaml script
save the file as gh-actions.yaml
Commit changes

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

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

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

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

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

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@v3
      - name: Set up Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: "npm"
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build:github-pages
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload dist repository
          path: "./dist"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Make sure the branch name (line 7) and the npm script that we created earlier (line 41) is set accordingly

Push your branch to github and that should automatically kick off your project.

Update: using Bun

If you are using Bun as your build tool, then this is the updated yaml to use.

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

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master"]

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

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

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

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@v3
      - name: Setup Bun
        uses: oven-sh/setup-bun@v1
      - name: Install dependencies
        run: bun install
      - name: Build
        run: bun run build:github-pages
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # Upload dist repository
          path: "./dist"
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

Conclusion