When I start a new app, I prefer right from the beginning to configure some sort of easy deployment (not necessarily full blown CI/CD, because, at least for my personal, small projects I don’t want to deploy every time, or I want to deploy from the local environment for various tests and tweaks - but below steps need just one more extra GitHub workflow step to become true CI/CD).

Configuring this before adding any features to the application comes with some healthy benefits, one of them being that it’s way easier to configure it while the app isn’t doing anything (not much configuration for the features), and then, while adding featues to the app that require special handling in the deployment configuration, it will be easy to change, incrementally at that point, for each newly added feature. Otherwise, adding a ton of features with special deployment requirements and then trying to configure deployment and get all to work has a higher complexity.

Lately, I’ve done more and more browser apps, basically static sites where the application is made only from the javascript running in the user’s browser. GitHub Pages is a very good environment for deploying these sort of small or personal projects, that don’t need any backend and don’t have intense traffic.

Configuring deployment for GitHub pages for frontend, browser apps made with tools like vite or create-react-app or written from scratch require a few steps to setup GitHub Pages deployment, steps which I always tend to forget, so I will write them here for the future me.

1. Create app

Create a browser app, a static site using vite or other site generators. Initialize a git repo with the app and publish it to GitHub (can also be private).

2. Install gh-pages

Install the gh-pages npm package:

npm install gh-pages --save-dev

3. Create deploy script

Add target to scripts section of package.config:

"scripts": {
  "deploy": "gh-pages -d dist"
},

4. Configure base

If hosted to a project site in github, e.g. https://<github-username>.github.io/myapp/, the myapp base part needs to be set in the build file.

Vite requires a base property in its vite.config.js:

export default defineConfig({
  ...
  base: '/myapp/',
})

5. Build & deploy

Now everything should be ready for deploy:

npm run build
npm run deploy

After a minute or so, the app will be available at https://<github-username>.github.io/myapp/.