@fe-blackbox/sdk

Lightweight browser SDK for white-screen detection and error monitoring.

Installation

Script Tag (CDN)

<!-- unpkg -->
<script src="https://unpkg.com/@fe-blackbox/sdk/dist/fe-blackbox.iife.min.js"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@fe-blackbox/sdk/dist/fe-blackbox.iife.min.js"></script>

Package Manager

# npm
npm install @fe-blackbox/sdk

# yarn
yarn add @fe-blackbox/sdk

# pnpm
pnpm add @fe-blackbox/sdk

Quick Start

IIFE (Script Tag)

<script src="https://unpkg.com/@fe-blackbox/sdk/dist/fe-blackbox.iife.min.js"></script>
<script>
  const client = FEBlackbox.initFEBlackbox({
    dsn: 'https://your-collector.example.com',
    projectId: 'my-app',
    env: 'production'
  });
</script>

ESM (Module Import)

import { initFEBlackbox } from '@fe-blackbox/sdk';

const client = initFEBlackbox({
  dsn: 'https://your-collector.example.com',
  projectId: 'my-app',
  env: 'production'
});

Configuration

FEBlackboxOptions

| Field | Type | Default | Description | |-------|------|---------|-------------| | dsn | string | — | Required. Collector endpoint URL. | | projectId | string | — | Required. Unique project identifier. | | env | string | — | Required. Environment name (e.g. production, staging). | | release | string | undefined | Application release / version string. | | privacy | object | {} | Privacy overrides — see below. | | whiteScreen | object | See below | White-screen detection options. | | transport | TransportConfig | See below | Transport & rate-limiting options. | | plugins | FEBlackboxPlugin[] | [] | Array of plugins. | | capturers | Capturer[] | Built-in set | Custom capturers replacing the defaults. |

whiteScreen Options

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | true | Enable white-screen detection. | | rootSelector | string | '#root' | CSS selector for the application root element. | | minVisibleNodes | number | 2 | Minimum visible DOM nodes to consider the page non-blank. | | stableAfterMs | number | 3000 | Time (ms) after navigation before detection activates. | | sampleIntervalMs | number | 1000 | Interval (ms) between blank-screen checks. | | consecutiveSamples | number | 3 | Consecutive blank samples before reporting. |

TransportConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | sampleRate | number | 1.0 | Event sampling rate (0–1). | | maxEventsPerSession | number | 50 | Maximum events per session. | | maxEventsPerMinute | number | 10 | Per-minute rate limit. | | flushIntervalMs | number | 5000 | Batch flush interval (ms). | | maxBatchSize | number | 10 | Maximum events per batch. |

API Reference

initFEBlackbox(options: FEBlackboxOptions): FEBlackboxClient

Initializes the SDK, installs all capturers, starts white-screen detection, and sets up plugins. Returns a FEBlackboxClient instance.

FEBlackboxClient

| Method | Signature | Description | |--------|-----------|-------------| | reportIncident | (reason: IncidentReason, extra?: ReportExtra) => Promise<void> | Manually report an incident. reason can be 'white-screen', 'js-error', 'manual', etc. extra accepts optional message, tags, and whiteScreen evidence. | | markRouteStable | (route?: string) => void | Call after a SPA route transition to reset white-screen detection for the new route. | | destroy | () => void | Tear down all capturers, plugins, and timers. |

ReportExtra

interface ReportExtra {
  message?: string;
  tags?: Record<string, string>;
  whiteScreen?: WhiteScreenEvidence;
}

Plugin System

Plugin Interface

interface FEBlackboxPlugin {
  name: string;
  setup?(client: FEBlackboxPluginClient): void | Promise<void>;
  beforeReport?(payload: IncidentPayload): IncidentPayload | null | Promise<IncidentPayload | null>;
  afterReport?(payload: IncidentPayload, response?: Response): void | Promise<void>;
  destroy?(): void | Promise<void>;
}

• setup — Called once after the SDK starts. Receives a client reference for triggering reports.
• beforeReport — Intercepts payloads before they are sent. Return null to drop the event.
• afterReport — Called after a payload is sent. Useful for logging or side-effects.
• destroy — Cleanup hook called when the client is destroyed.

Built-in Plugins

| Package | Description | |---------|-------------| | @fe-blackbox/plugin-debug | Remote debugging support. | | @fe-blackbox/plugin-screenshot | Captures a screenshot attachment on incident. | | @fe-blackbox/plugin-replay | Records a session replay clip around the incident. |

Usage Example

import { initFEBlackbox } from '@fe-blackbox/sdk';
import { screenshotPlugin } from '@fe-blackbox/plugin-screenshot';
import { replayPlugin } from '@fe-blackbox/plugin-replay';

const client = initFEBlackbox({
  dsn: 'https://your-collector.example.com',
  projectId: 'my-app',
  env: 'production',
  plugins: [screenshotPlugin(), replayPlugin()]
});

Custom Capturers

Capturer Interface

interface Capturer {
  readonly name: string;
  install(cleanup: Array<() => void>): void;
  snapshot(): unknown;
}

• name — Unique identifier (e.g. 'console', 'error').
• install — Set up event listeners. Push teardown functions into cleanup.
• snapshot — Return collected entries at the time of an incident report.

Built-in Capturers

| Capturer | Name | Collects | |----------|------|----------| | ConsoleCapturer | console | console.warn / console.error entries | | ErrorCapturer | error | Uncaught errors and unhandled rejections | | FetchCapturer | fetch | Fetch/XHR request & response metadata | | ResourceCapturer | resource | Failed resource loads (scripts, images, etc.) |

Writing a Custom Capturer

import type { Capturer } from '@fe-blackbox/sdk';

class CustomCapturer implements Capturer {
  readonly name = 'custom';
  private entries: string[] = [];

  install(cleanup: Array<() => void>): void {
    const handler = (e: Event) => this.entries.push(e.type);
    window.addEventListener('click', handler);
    cleanup.push(() => window.removeEventListener('click', handler));
  }

  snapshot(): string[] {
    return [...this.entries];
  }
}

Replacing Default Capturers

Pass a capturers array to override the built-in set entirely:

import { initFEBlackbox, ConsoleCapturer, ErrorCapturer } from '@fe-blackbox/sdk';

const client = initFEBlackbox({
  dsn: 'https://your-collector.example.com',
  projectId: 'my-app',
  env: 'production',
  capturers: [new ConsoleCapturer(), new ErrorCapturer()]
});

Transport & Reliability

The ESM entry (@fe-blackbox/sdk) uses an enhanced transport client that provides:

• Batch sending — Events are queued and flushed at regular intervals (flushIntervalMs).
• Offline caching — Events are persisted via IndexedDB when the browser goes offline and replayed when connectivity returns.
• Automatic retry — Failed batches are re-enqueued for the next flush cycle.

The IIFE bundle (fe-blackbox.iife.min.js) also includes the full transport layer with the same capabilities.

Configure via transport:

initFEBlackbox({
  dsn: 'https://your-collector.example.com',
  projectId: 'my-app',
  env: 'production',
  transport: {
    maxBatchSize: 5,
    flushIntervalMs: 3000
  }
});

Bundle Size

| Build | Raw | Gzip | |-------|-----|------| | IIFE (fe-blackbox.iife.min.js) | ~14 KB | ~4.6 KB | | ESM | Tree-shakeable | — |

Browser Support

ES2022+ — all modern browsers (Chrome 94+, Firefox 93+, Safari 15.4+, Edge 94+).

License

MIT