Deploy WebXR to GitHub Pages

A simple demo that you can use as a template for your own WebXR projects. It uses Vite to bundle the application files and GitHub Pages to host them. Whenever you push changes to GitHub it will deploy them automatically with a GitHub Action. To use it you will need to sign up to GitHub, but it's free and the defacto standard for source code hosting.

Live demo: https://learnhub.github.io/DeployWebXR/

If you are using AI-assisted development you can just point it at this project and tell it to:

update this project to use the build and deploy approach described here: https://github.com/LearnHub/DeployWebXR

Sharing on ClassVR

The easiest way to share the published application is to scan the URL as a QR code from your ClassVR headset:

You can also add the URL to a shared playlist from the management pages:

• Select the playlist you want to add to and then click the Add New Website action button
• Enter the deployment URL and click [Add Website
• This creates a track in this playlist that can be managed from within the ClassVR Portal and sent to headsets

Quick Start

1. Fork or clone this repository
2. Update base in vite.config.js to match your repository name
3. Push to GitHub
4. Enable GitHub Pages (see Enabling GitHub Pages)

Project Structure

├── .github/workflows/deploy.yml  # Automated deployment
├── index.html                    # Entry HTML file
├── main.js                       # Three.js WebXR scene
├── package.json                  # Dependencies and scripts
└── vite.config.js                # Build configuration

How It Works

Vite Build Tool

Vite bundles your JavaScript and assets into optimized static files. Key benefits:

• Hot module reload during development
• Automatic dependency bundling (Three.js, etc.)
• ES module support out of the box

The vite.config.js file configures the build:

import { defineConfig } from 'vite';

export default defineConfig({
  base: '/your-repo-name/',  // ← Change this to your repository name
  build: {
    outDir: 'dist',
  },
});

The base path is critical—it tells Vite where your site will be hosted so asset URLs resolve correctly.

GitHub Actions Workflow

The .github/workflows/deploy.yml file automates deployment. When you push to main:

1. Checkout - Gets your code
2. Setup Node - Installs Node.js
3. Install dependencies - Runs npm ci
4. Build - Runs npm run build, creating the dist/ folder
5. Deploy - Uploads dist/ to GitHub Pages

See GitHub Actions documentation for more details.

GitHub Pages

GitHub Pages serves static files from your repository. With the Actions workflow, it serves the built dist/ folder at:

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

See GitHub Pages documentation for more details.

Enabling GitHub Pages

1. Go to your repository on GitHub
2. Click Settings → Pages
3. Under "Build and deployment", set Source to GitHub Actions

The next push to main will trigger deployment.

Local Development

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Preview production build locally
npm run preview

Adapting for Your Project

Minimal Changes

1. Replace main.js with your WebXR code
2. Update base in vite.config.js to your repository name
3. Update name and description in package.json

Adding Dependencies

npm install <package-name>

Common WebXR packages:

• three - 3D rendering (Three.js docs)
• @react-three/fiber - React renderer for Three.js
• aframe - Declarative WebXR framework (A-Frame docs)

WebXR Requirements

WebXR requires a secure context:

• HTTPS (GitHub Pages provides this automatically)
• localhost (works for local development)

See the WebXR Device API documentation for browser support and features.

Troubleshooting

Build fails: "Dependencies lock file not found"

Ensure package-lock.json is committed:

npm install
git add package-lock.json
git commit -m "Add package-lock.json"
git push

Assets not loading (404 errors)

Check that base in vite.config.js matches your repository name exactly, including case.

WebXR not available

• Ensure you're accessing via HTTPS (not HTTP)
• Check browser support at caniuse.com/webxr
• On desktop, install a WebXR emulator extension for testing

Node Package Manager

This demo uses the Node Package Manager (npm) to manage scripts and libraries like vite. This is a common way of managing projects even if they don't use NodeJS because npm is has a rich set of tools and is well documented. It is not a requirement and you there are many other ways to deploy code to GitHub.

Resources

• Vite Documentation
• Three.js Documentation
• WebXR Device API (MDN)
• GitHub Pages Documentation
• GitHub Actions Documentation