Prism Debugger

Real-time debugger for Janative (JavaScript + Native) mobile apps. WebSocket broker between native SDKs and Web UI with event console, performance timeline, and reporting.

Quick Start

npx prism-debugger

Or install globally:

npm install -g prism-debugger
prism

Server starts and prints the config summary:

  Prism Debugger
  ─────────────────────────────────────
  Config:    defaults (no .env, run prism init)
  HTTP:      http://localhost:8080
  UI:        http://192.168.1.10:8080/?token=ui-dev-token
  WS Mobile: ws://192.168.1.10:8080/ws/mobile
  WS iOS:    ws://192.168.1.10:8080/ws/ios
  Plugins:   context-device-event-logger

Open the UI link in your browser — that's it.

Configuration

CLI flags

prism -p 8097                       # set port
prism --ios-token my-secret         # legacy iOS SDK auth token
prism --ui-token my-secret          # Web UI auth token
prism --plugins none                # disable plugins
prism --log-dir ./my-logs           # context event log directory

.env file

Generate a config in the current directory:

prism init

This creates a .env file with all available options:

PORT=8097
CLIENT_AUTH_KEYS=ios-dev-token,android-dev-token
IOS_AUTH_KEYS=ios-dev-token
UI_AUTH_KEYS=ui-dev-token
HEARTBEAT_TIMEOUT_SEC=30
RATE_LIMIT=30
MAX_PAYLOAD_BYTES=262144
RING_BUFFER_SIZE=500
ENABLED_PLUGINS=context-device-event-logger
CONTEXT_EVENT_LOG_DIR=./logs/context-events

Priority: CLI flags > .env file > defaults.

Options reference

| Option | CLI flag | Env variable | Default | Description | |--------|----------|--------------|---------|-------------| | Port | -p, --port | PORT | 8080 | HTTP and WebSocket port | | Client token | — | CLIENT_AUTH_KEYS | ios-dev-token,android-dev-token | Auth tokens for new mobile SDKs | | iOS token | --ios-token | IOS_AUTH_KEYS | ios-dev-token | Legacy auth token for iOS SDK | | UI token | --ui-token | UI_AUTH_KEYS | ui-dev-token | Auth token for Web UI (comma-separated for multiple) | | Plugins | --plugins | ENABLED_PLUGINS | context-device-event-logger | Comma-separated list of plugins | | Log dir | --log-dir | CONTEXT_EVENT_LOG_DIR | ./logs/context-events | Directory for JSONL event logs | | Heartbeat | — | HEARTBEAT_TIMEOUT_SEC | 30 | Seconds before marking device offline | | Rate limit | — | RATE_LIMIT | 30 | Max events per second per debugger | | Payload size | — | MAX_PAYLOAD_BYTES | 262144 | Max message size (bytes) | | Ring buffer | — | RING_BUFFER_SIZE | 500 | Message history per debugger |

WebSocket endpoints

| Endpoint | Purpose | |----------|---------| | /ws/mobile?token=<CLIENT_TOKEN> | Mobile SDK connection | | /ws/ios?token=<IOS_TOKEN> | iOS SDK connection | | /ws/android?token=<CLIENT_TOKEN> | Android SDK connection | | /ws/ui?token=<UI_TOKEN> | Web UI connection |

HTTP API

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /health | Health check | | GET | /api/connect-info | Server IP and port for QR connect | | GET | /api/debuggers | List connected debuggers | | GET | /api/debuggers/:id/messages | Message history for a debugger | | POST | /api/debuggers/:id/send | Send command to a debugger |

Smoke Checks

Load smoke:

npm run smoke:load

Android round-trip smoke for an already running demo app:

npm run smoke:android -- --port 8097

The script finds an online Android debugger, sends command.execute, and waits for command.received in message history.

Web UI

Open http://localhost:<port>/?token=<UI_TOKEN> in your browser.

Features:

• Live event console with level/category filters
• Performance timeline (Gantt chart) with badge grouping
• PerfPoint detail popups with extra data
• HTML / CSV / JSON report export
• QR code for quick SDK connection
• Light and dark themes

Plugins

Built-in plugin context-device-event-logger writes JSONL logs per context:

logs/context-events/{bundleId}/{device}/{sessionId}/{context}.log

Disable all plugins:

prism --plugins none

License

MIT