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).

  • CloudXR.js package tarball from NGC (initial distribution model).

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. 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 / 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, see Quick Start Guide and End-to-End Example.

Runtime Configuration#

Before connecting, configure:

  • Server IP/host and signaling port

  • Connection mode (direct or proxy)

  • Rendering and stream settings for target device/network

See 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/device setup in Client Setup Guide.

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

Troubleshooting#