Serving a JavaScript project built using Vite from GitHub Pages#

Creating a Vite project#

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

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

My project is called hmb-map.

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

1
.gitignore
2
counter.js
3
index.html
4
javascript.svg
5
main.js
6
package.json
7
public/vite.svg
8
style.css

Now cd hmb-map and run this:

1
npm install

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

Start the Vite development server like so:

1
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:

1
name: Deploy
2

3
on:
4
  push:
5
    branches:
6
      - main
7

8
jobs:
9
  build:
10
    name: Build
11
    runs-on: ubuntu-latest
12
    steps:
13
      - name: Checkout repo
14
        uses: actions/checkout@v3
15
      - name: Setup Node
16
        uses: actions/setup-node@v3
17
      - name: Install dependencies
18
        run: npm install
19
      - name: Configure vite
20
        run: |
21
          echo 'export default {
22
            base: "/${{ github.event.repository.name }}/"
23
          }' > vite.config.js
24
      - name: Build project
25
        run: npm run build
26
      - name: Upload Pages artifact
27
        uses: actions/upload-pages-artifact@v2
28
        with:
29
          path: dist
30
  deploy:
31
    needs: build
32
    permissions:
33
      pages: write
34
      id-token: write
35
    environment:
36
      name: github-pages
37
      url: ${{ steps.deployment.outputs.page_url }}
38
    runs-on: ubuntu-latest
39
    steps:
40
      - name: Deploy to GitHub Pages
41
        id: deployment
42
        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 username.github.io/repo-name/ - 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:

1
echo 'export default {
2
  base: "/${{ github.event.repository.name }}/"
3
}' > 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:

1
export default {
2
  base: "/hmb-map/"
3
}

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 https://github.com/simonw/hmb-map/settings/pages and set GitHub Actions as the source for my Pages builds:

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 https://github.com/simonw/hmb-map/ - the GitHub Pages site it deploys is at https://simonw.github.io/hmb-map/