Deploying a create-3dverse-app to GitHub Pages

If you use GitHub for version control, you can leverage GitHub Pages as an easy way to deploy your client application to your users. This guide explains how to set up a continuous integration pipeline to deploy your 3dverse application to GitHub Pages whenever you push to your main branch.

Prepare Your Project

Make sure your project can build locally:

npm run build

You should be able to see your build files in the /dist folder.

Add a GitHub Actions Workflow

In your repository, create a workflow file at:

.github/workflows/deploy.yml

Add the following content:

name: Deploy to GitHub Pages

on:
    push:
        branches:
            - main

permissions:
    contents: read
    pages: write
    id-token: write

jobs:
    build:
        runs-on: ubuntu-latest
        steps:
            - name: Checkout source
              uses: actions/checkout@v4

            - name: Setup Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: 22

            - name: Install dependencies
              run: npm install

            - name: Build project
              run: npm run build

            - name: Upload build output
              uses: actions/upload-pages-artifact@v3
              with:
                  path: ./dist

    deploy:
        environment:
            name: github-pages
            url: ${{ steps.deployment.outputs.page_url }}
        runs-on: ubuntu-latest
        needs: build
        steps:
            - name: Deploy to GitHub Pages
              id: deployment
              uses: actions/deploy-pages@v4

Public base path

If you intend to use the URL scheme provided by GitHub Pages (https://<username>.github.io/<repository-name>/), you will need to configure the base path for the project in order to serve assets from the appropriate path. This is done by adding the base parameter to your Vite build command in package.json.

{
  "name": "my-app",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build --base=/my-repository/",
  }
...
}

Enable GitHub Pages

Make sure everything is committed and pushed to your main branch.

1. Go to your repository on GitHub.
2. Navigate to Settings → Pages.
3. Under Source, choose GitHub Actions.

Deploy

Now, every time you push to the main branch, GitHub Actions will automatically:

1. Install dependencies
2. Build your project
3. Deploy the contents of the /dist folder to GitHub Pages

Have a look at the Actions tab on GitHub to keep track of your deployment's progress.

After a short time, your application should be publicly available at:

https://<username>.github.io/<repository-name>/