xpace-server

Local WebSocket relay server for developing Ubox Xpace experiences. Simulates the Ubox messaging infrastructure so multiple browser apps can communicate during development — across tabs or across devices on the same network.

Usage

Run from the root of a Ubox experience project:

npx @ubox-tools/xpace-server

If an apps/ directory is found, its contents are served over HTTP and each app gets the UboxClient shim automatically injected — no changes to your HTML files needed.

xpace-server running
  WebSocket  ->  ws://192.168.1.10:3001
  Dashboard  ->  http://192.168.1.10:3000
  Shim       ->  http://192.168.1.10:3000/shim.js
  Apps       ->  http://192.168.1.10:3000/apps/

Open the dashboard URL in a browser to monitor connected apps, shared variables, and the live message log. Open any app URL from any device on the network.

How it works

ubox-data-xpace connects to a UboxClient singleton. xpace-server provides a drop-in browser shim that replaces that singleton with a plain WebSocket pointing at the local relay. The relay broadcasts every message to all other connected clients — the same contract as the real Ubox server.

The shim is served at /shim.js and injected automatically into HTML files served from /apps/. For apps served elsewhere, add it manually before ubox-data-xpace:

<script src="http://192.168.1.10:3000/shim.js"></script>
<script src="ubox-data-xpace.js"></script>

Options

| Option | Default | Description | |---|---|---| | -p, --port <n> | 3001 | WebSocket relay port | | --dash-port <n> | 3000 | Dashboard HTTP port | | --host <ip> | auto-detect | Override the advertised host IP | | --apps-dir <path> | ./apps | Directory to serve as apps | | --no-dashboard | — | Disable the dashboard | | --no-log | — | Disable message logging to stdout | | --log-filter <cmds> | all | Comma-separated commands to log |

Programmatic use

const { createServer } = require('@ubox-tools/xpace-server');

const { wss, close } = createServer({
  port: 3001,
  dashPort: 3000,
  appsDir: '/path/to/apps',
});