@fe-blackbox/plugin-debug

Remote debugging plugin for the FE-Blackbox SDK.

Alpha — This plugin is under active development. APIs may change between minor versions.

Installation

npm install @fe-blackbox/plugin-debug

Quick Start

import FEBlackbox from '@fe-blackbox/sdk';
import { debugPlugin } from '@fe-blackbox/plugin-debug';

FEBlackbox.init({
  dsn: 'http://localhost:3001',
  projectId: 'my-app',
  env: 'development',
  plugins: [
    debugPlugin({
      brokerUrl: 'ws://localhost:3001/debug/ws',
      token: 'my-debug-token'
    })
  ]
});

How It Works

The plugin establishes a WebSocket connection to the FE-Blackbox collector's debug broker. Once connected, it exposes a Chrome DevTools Protocol (CDP)-compatible interface that allows a remote inspector to:

• Runtime — Evaluate JavaScript expressions in the page context
• Console — Stream live console output (debug, info, warn, error)
• Network — Observe network requests and responses
• DOM — Query and inspect DOM nodes

All communication happens over a single WebSocket channel, making it suitable for debugging devices on remote networks.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | brokerUrl | string | (required) | WebSocket URL of the debug broker endpoint | | token | string | (required) | Authentication token for the debug session | | autoConnect | boolean | true | Connect automatically on plugin setup | | reconnect | boolean | undefined | Reconnect automatically when the connection drops |

Manual Connection

If you need to control when the debug session starts, disable auto-connect:

import { DebugClient } from '@fe-blackbox/plugin-debug';

const client = new DebugClient({
  brokerUrl: 'ws://localhost:3001/debug/ws',
  token: 'my-debug-token',
  reconnect: true
});

// Connect later
client.connect();

// Disconnect when done
client.destroy();

Exports

| Export | Description | | --- | --- | | debugPlugin | Factory function returning a FEBlackboxPlugin | | DebugClient | Low-level WebSocket debug client | | RuntimeAgent | CDP Runtime domain agent |

License

MIT