Serving a JavaScript project built using Vite from GitHub Pages

I figured out how to serve a JavaScript project built using Vite using GitHub Pages and a custom build script that runs using GitHub Actions.

See Serving a custom vector web map using PMTiles and maplibre-gl for details of that project.

Creating a Vite project

I started with a "vanilla" JavaScript Vite project. I used the following command to create it:

npx create-vite@latest hmb-map --template vanilla

My project is called hmb-map.

This creates a hmb-map/ directory containing the following files:


Now cd hmb-map and run this:

npm install

That installs Vite and a few other dependencies into node_modules/.

Start the Vite development server like so:

npm run dev

This spits out a URL like http://localhost:5173/ - that page uses Vite's live reloading mechanism, so any changes you make to the code should be instantly reflected in your browser, without having to reload the page.

You can npm install x packages there, then use import x from 'x' in your main.js code and Vite will automatically bundle them into your project.

Deploying that project to GitHub Pages

The directory structure created by npx create-vite has almost everything you need to push it to GitHub. But we want the build process to run on every push and deploy a built version of the code to GitHub Pages.

To do that, add a .github/workflows/deploy.yml file containing the following:

name: Deploy

      - main

    name: Build
    runs-on: ubuntu-latest
      - name: Checkout repo
        uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
      - name: Install dependencies
        run: npm install
      - name: Configure vite
        run: |
          echo 'export default {
            base: "/${{ }}/"
          }' > vite.config.js
      - name: Build project
        run: npm run build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v2
          path: dist
    needs: build
      pages: write
      id-token: write
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

There are a few things going on here.

The build job mainly runs npm run build, which creates a dist/ folder suitable for deployment.

I had to make one change here. GitHub Pages defaults to deploying to - but Vite expects the application to be running at the root of a site, not inside a folder.

The fix for that is to configure Vite to use a base path. My Actions workflow does that like so:

echo 'export default {
  base: "/${{ }}/"
}' > vite.config.js

This uses GitHub Actions expression syntax to get the name of the repository, then writes a vite.config.js file containing the following:

export default {
  base: "/hmb-map/"

This causes the npm run build step to bundle for code hosted at /hmb-map/ instead of /.

At the end of the build job the actions/upload-pages-artifact action is used to upload the dist/ folder produced by Vite as an artifact.

This artifact is then deployed by the actions/deploy-pages action at the end of the deploy job.

Enabling GitHub Pages via GitHub Actions

There was one remaining configuration step: I had to visit and set GitHub Actions as the source for my Pages builds:

Screenshot of the Pages settings showing the GitHub Actions source selection menu

Adding additional files to public/

For my application I needed a file called hmb.pmtiles to be hosted in the root directory of the site.

Vite has a public directory concept for this. Any files you add to the public/ directory will be served from the root by npm run dev and will be bundled into the root of the built asset as well.

The final result

You can see the resulting repo at - the GitHub Pages site it deploys is at

Created 2023-10-23T21:14:07-07:00, updated 2023-10-23T22:01:19-07:00 · History · Edit