React Sample Workflow#

This sample workflow documents the end-to-end process for the CloudXR.js React sample: an advanced sample using React Three Fiber, React Three XR, and React Three UIKit to create immersive XR streaming experiences with rich 3D user interfaces.

Prerequisites#

  • CloudXR Runtime server is running with auto-webrtc device profile.

  • Node.js v20 or later (for local development) or Docker (for containerized setup).

Option A: Docker (Quick Start)#

Build and run the sample in a container with no local toolchain required:

# Build the Docker image
docker build -t cloudxr-react-sample --build-arg EXAMPLE_NAME=react .

# Run the container
docker run -d --name cloudxr-react-sample -p 8080:80 -p 8443:443 cloudxr-react-sample

Open http://localhost:8080 (HTTP) or https://localhost:8443 (HTTPS) in your browser.

Note

When using HTTPS, accept the self-signed certificate warning in your browser.

To stop and remove the container:

docker stop cloudxr-react-sample && docker rm cloudxr-react-sample

Option B: Local Development#

  1. Clone the samples repository and navigate to the sample directory:

    git clone https://github.com/NVIDIA/cloudxr-js-samples.git
cd cloudxr-js-samples/react

  2. Refer to the requirements above, then install CloudXR.js from the downloaded tarball:

    npm install </path/to/nvidia-cloudxr-<version>.tgz>

  3. Install the remaining dependencies:

    npm install

  4. Build the sample:

    npm run build

  5. Start the web server:

    • HTTP (local development):

      npm run dev-server

    • HTTPS (device testing or production-like):

      npm run dev-server:https

Basic Usage#

  1. Configure Connection: Enter your CloudXR server IP address, set the port (default: 49100), and select AR or VR immersive mode.

  2. Adjust Settings (optional): Configure per-eye resolution (perEyeWidth must be a multiple of 16 and perEyeHeight must be a multiple of 64), target frame rate, streaming bitrate, and XR reference space.

  3. Start Streaming: Click CONNECT to initiate the XR session and grant XR permissions when prompted.

Tip

For the fastest way to get a server running, try the LÖVR sample: a lightweight VR framework ideal for testing your CloudXR.js client setup. For setup commands, refer to Quick Start Guide and End-to-End Example.

Runtime Configuration#

Before connecting, configure:

  • Server IP or host and signaling port

  • Connection mode (direct or proxy)

  • Rendering and stream settings for target device or network

Refer to Session API and Performance Guide for tuning guidance.

Validation Flow#

  1. Validate from desktop browser first (IWER automatically loads for WebXR emulation).

  2. Validate from headset after browser or device setup in Client Setup Guide.

  3. For HTTPS mode, configure WSS proxy in WebSocket Proxy Setup.

Troubleshooting#