Build & Deploy

This tutorial shows you how to build for production and deploy to GitHub Pages so others can experience your creation.

Production build process

Your starter app is already configured with Vite plugins that automatically optimize assets during build. When you run npm run build, it:

Bundles and minifies your JavaScript/TypeScript code.

Compresses GLTF models with Draco and optimizes textures.

Generates a deployable static site in the dist/ folder.

Building your project

Navigate to your project directory and run:

npm run build

This creates a dist/ folder with your optimized application. The build automatically:

Compresses your GLTF models using Draco compression.

Optimizes textures with KTX2 compression (when available).

Bundles and minifies JavaScript.

Copies public assets.

Asset optimization

Your starter app includes the @iwsdk/vite-plugin-gltf-optimizer plugin that automatically compresses GLTF models and textures during build.

Current configuration

In your vite.config.ts, you can see the optimizer is already configured:

import { optimizeGLTF } from '@iwsdk/vite-plugin-gltf-optimizer';

export default defineConfig({
  plugins: [
    // ... other plugins
    optimizeGLTF({
      level: 'medium',
    }),
  ],
});

Optimization levels

The plugin offers three preset levels:

light: Fast build, moderate compression.

medium: Balanced build time and compression.

aggressive: Slower build, maximum compression.

KTX2 compression requirements

The optimizer uses KTX2 compression by default for better texture compression. If you don’t have KTX-Software installed, you’ll see this warning:

⚠️  KTX-Software not found (missing "ktx" CLI). Skipping KTX2 compression.
   Install from: https://github.com/KhronosGroup/KTX-Software/releases

The build will fall back to standard texture optimization instead of crashing, but installing KTX-Software gives you better compression results. Download and install it from the KTX-Software releases page for optimal texture compression.

Advanced configuration

For more control, you can customize specific options:

optimizeGLTF({
  level: 'medium',
  verbose: true, // Show optimization details
  geometry: {
    compress: 'draco', // Draco compression
    quality: 0.8, // Higher = better quality, larger size
  },
  textures: {
    mode: 'auto', // Automatic texture compression
    quality: 0.75, // Texture compression quality
    maxSize: 1024, // Maximum texture resolution
  },
});

During build, you’ll see optimization results showing significant file size reductions for your GLTF models and textures.

Deploying to GitHub pages

GitHub Pages provides free hosting perfect for WebXR applications.

Step 1: Configure base path

Update your vite.config.ts to set the correct base path:

export default defineConfig({
  base: '/your-repository-name/', // Must match your GitHub repo name
  // ... rest of your existing config
});

Step 2: Manual deployment

Install the gh-pages tool and deploy:

# Install deployment tool
npm install -D gh-pages

# Build and deploy
npm run build
npx gh-pages -d dist

Step 3: Enable GitHub pages

Go to your repository on GitHub.

Click Settings > Pages.

Set Source to Deploy from a branch.

Select the gh-pages branch.

Click Save.

Your app will be live at: https://yourusername.github.io/your-repository-name/

Automated deployment with GitHub actions

For automatic deployment on every push, create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        if: github.ref == 'refs/heads/main'
        with:
          github_token: $
          publish_dir: ./dist