Building a Snowpack Website on Github Pages

tldr; here is a diff of the changes needed from the starter project. You also need to set the repo to serve Github pages from /docs instead of /(root)

On a hobby project recently I wanted to try out Snowpack. It had a few nice benefits when considered against heavy-weights like webpack, but the main one that had me interested was the fact you need (almost) no configuration to get a simple React+Typescript project up and running.

In this blog post I want to show you how you can set up a simple snowpack build and get it automatically building and deploying to a Github website every time you push your code up.

Setting Up a Starter Project

First let's kick off a starter Snowpack project, you can skip this step if you already have a Snowpack project up and running. Feel free to tweak the project name and template as you see fit.

npx create-snowpack-app snowpack-actions --template @snowpack/app-template-react-typescript

Once the project is created you can now move into the directory and run the Snowpack dev server:

cd snowpack-actions
npm start

This will open up a browser tab for you, as you make changes to files in the src/ folder, snowpack will automatically rebuild and reflect the changes in your browser.

Building on Push with a Github Action

First we need to create a workflow for running the Snowpack build in .github/workflows/snowpack.yml with the following contents. This tells Github to trigger a snowpack build and commit the result after every push we do.

name: Snowpack
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js 14.x
        uses: actions/setup-node@v1
        with:
          node-version: 14.x
      - run: npm ci
      - run: npm run build
      - name: Committing changes
        uses: EndBug/add-and-commit@v7
        with:
          author_name: Snowpack Build
          author_email: actions@github.com

As of right now, Github has a limitation where the only subfolder you can serve a pages site from is the docs/ folder of a repo. Due to this we need to tell Snowpack to output our files in the docs/ folder by updating snowpack.config.js buildOptions to be as follow:

  buildOptions: {
    // put the build files in /docs
    out: 'docs',
    // put the meta snowpack build files under snowpack instead of _snowpack since Github special-cases underscore prefixed folders
    metaUrlPath: 'snowpack'
  }

One last final change to change the starter app URLs to be relative rather than absolute to ensure they render on the Github pages site. Open public/index.html and update /favicon.ico to favicon.ico and /dist/index.js to dist/index.js.

From here, commit all your changes and push the up to Github.

git add .
git push origin main

Now just one more configuration to do via the Github web UI, navigate to your repo settings and select your primary branch and set the folder to /docs.

Done!

Now your webpage should render once Github pages update their cache with the latest build (this can take a little bit, sometimes it helps to cache-bust by adding query string parameters e.g. ?test=123 and disable cache in the network tab of the browser devtools, Github likes to cache pages sites aggressively).

Here is the link to the deployed site for this blog post. You can find the git commit of all the changes needed here.