Getting Started

Unlike regular web development where you can run your project locally and then immediately preview the website, WebXR websites usually require a few more steps to allow preview on headsets:

1. You need to host the website locally or with a secure server.

2. Besides that, WebXR must be served over HTTPS, which means you may need to generate a local SSL certificate.

Host Locally

If you host your website locally, the access is limited to devices on the same local network (e.g. WiFi).

Step 1: Generate SSL Certificates 

You can use mkcert to generate a local SSL certificate, install if you haven't already:

For example, on macOS:

brew install mkcert

Then open terminal and run:

mkcert -install

mkcert localhost [replace your ip address here]

For example:

mkcert localhost 127.0.0.1

Once you've successfully done the steps, you should see localhost+1.pem and localhost+1-key.pem showing up in your current directory.

Step 2: Configure SSL Certificates 

Go to your project directory, create vite.config.js if there isn't one, and copy paste the following:

export default defineConfig({

  server: {

    host: '0.0.0.0',

    https: {

      key: fs.readFileSync('localhost+1-key.pem'),

      cert: fs.readFileSync('localhost+1.pem')

    }

  }

});

Then go package.json to and make the following is there:

"scripts": {

    "dev": "vite",

    "build": "vite build"

}

Step 3: Build and Deploy 

Build your project in terminal:

npx vite build

This command generates a folder called /dist  that contains the compiled files.

Then serve it on local network:

vite preview --host

Then you should see something like this in the terminal:
  VITE vX.X.X  ready in Xms

  ➜  Local:    https://localhost:4173/

  ➜  Network:  https://X.X.X.X:4173/

Visit local address if you only need to visit via your computer. Visit network address for any device on the same network (this is what you should use for your headset!).

Host on GitHub Pages

If you want devices outside of your local network to visit your website, and also want it to be served constantly, you need to deploy your website on a server. GitHub Pages is a good option for doing this because it's all free and built-in with GitHub.

Step 1: Host Locally

All the steps in the previous section are also needed here, so please go back and complete them if you haven't already!

Step 2: Follow GitHub Pages Instructions

The official documentation has all the steps you need to host on GitHub Pages. It's very simple and shouldn't take much time.

Step 3: Update Settings

All GitHub Pages websites' address follow this convention: https://username.github.io/repo-name, make sure you add repo-name to the base field of the configuration:

export default defineConfig({

base: '/repo-name/',

  server: {

    host: '0.0.0.0',

    https: {

      key: fs.readFileSync('localhost+1-key.pem'),

      cert: fs.readFileSync('localhost+1.pem')

    }

  }

});

Step 4: Install Package

Install gh-pages for deployment:

npm install gh-pages --save-dev

Step 5: Build and Deploy 

One last step, build and deploy the project with GitHub Pages:

npx vite build

npx gh-pages -d dist