Bugline Web SDK

The client-side JavaScript SDK for Bugline. It turns client-side user feedback and unhandled errors into developer-ready bug reports with automatic device, browser, and OS context collection.

Features

• Programmatic Reporting: Manually report feedback or capture exceptions.
• Auto-Capture: Automatically listens for unhandled errors and promise rejections on the window object.
• Client Metadata: Auto-detects browser name/version, OS name/version, screen URL, resolution, language, and user agent.
• Premium Feedback Widget: Optional floating bubble widget with a side panel, interactive inputs, and responsive layout, matching dark and light mode preferences.

Screenshots. The widget renders screenshots with html2canvas-pro, installed automatically as a dependency and resolved through your bundler. It is loaded via dynamic import(), so bundlers code-split it and it is only fetched the first time a user captures a screenshot. Nothing is loaded from a CDN at runtime, so the SDK works offline and needs no script-src CSP exception. If your page already defines window.html2canvas, that build is used instead.

Installation

Install the package via npm:

npm install @xtatistix/bugline-web

Initialization

Initialize the SDK at the entry point of your application (e.g., index.js, main.js, or _app.js).

Bugline is available as a named export (recommended) and a default export — both reference the same singleton, so either import style works:

import { Bugline } from "@xtatistix/bugline-web"; // recommended
// import Bugline from "@xtatistix/bugline-web";  // also works

Store your credentials in environment variables rather than hardcoding them. The canonical names (Next.js shown; use VITE_/EXPO_PUBLIC_ prefixes for those frameworks) are:

NEXT_PUBLIC_BUGLINE_API_KEY=bl_your_api_key_here
NEXT_PUBLIC_BUGLINE_ENDPOINT=https://your-bugline-api.com/v1/reports

import { Bugline } from "@xtatistix/bugline-web";

Bugline.init({
  apiKey: process.env.NEXT_PUBLIC_BUGLINE_API_KEY,        // Required
  endpoint: process.env.NEXT_PUBLIC_BUGLINE_ENDPOINT,     // Optional, defaults to '/v1/reports'
  appVersion: "1.0.0",                                    // Optional
  environment: "production",                              // Optional
  captureErrors: true,                                    // Optional (defaults to true)
  showWidget: true,                                       // Optional (defaults to true)
  theme: "dark",                                          // Optional: 'dark' or 'light' (defaults to 'dark')
  metadata: {                                             // Optional: Global metadata appended to all reports
    companyId: "corp_123"
  }
});

Hidden "Easter Egg" trigger

To hide the floating button and instead open the panel after a number of clicks on an element of your choosing, pass an easterEgg object:

Bugline.init({
  apiKey: process.env.NEXT_PUBLIC_BUGLINE_API_KEY,
  easterEgg: {
    enabled: true,
    selector: "#company-logo", // CSS selector of the element to click
    clicks: 5,                 // consecutive clicks required (defaults to 5)
    timeout: 3000              // ms window to complete the clicks (defaults to 3000)
  }
});

Usage

1. Interactive Feedback Widget

If showWidget is set to true, a modern floating button will appear on the bottom right of the screen. Clicking it opens a beautiful, slide-out feedback panel. The user inputs their message, sees the automatically captured client context, and submits.

2. Programmatic Reports

Send reports from any part of your code manually:

import { Bugline } from "@xtatistix/bugline-web";

// Submit generic user feedback
Bugline.sendReport({
  text: "The checkout page button is unresponsive on click",
  category: "feedback", // Optional
  severity: "medium",   // Optional: 'critical' | 'high' | 'medium' | 'low'
                        // The older log levels still work and are translated:
                        // 'error' → 'high', 'warning' → 'medium', 'info' → 'low'.
                        // Omit it and the report is sent with no severity.
  metadata: {
    cartTotal: 129.99
  }
});

3. Programmatic Exception Capture

Log caught errors directly to Bugline:

import { Bugline } from "@xtatistix/bugline-web";

try {
  executeRiskyOperation();
} catch (error) {
  Bugline.captureException(error, {
    additionalContext: "Failed during risky payment processing"
  });
}

4. Teardown

init() is idempotent — calling it twice logs a warning and does nothing, so React StrictMode and Fast Refresh will not produce duplicate widgets or duplicate error listeners. To detach the SDK completely (widget DOM, injected stylesheet, and all global listeners), call destroy():

import { useEffect } from "react";
import { Bugline } from "@xtatistix/bugline-web";

useEffect(() => {
  Bugline.init({ apiKey: "bl_your_api_key_here" });
  return () => Bugline.destroy();
}, []);

destroy() is safe to call repeatedly and safe to call when init() was never called. Configuration is retained, so a later init() re-attaches with the same options.

Configuration API Reference

The Bugline.init(options) takes an options object with the following configuration options:

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | apiKey | string | Required | The API key generated for your app in the Bugline dashboard. | | endpoint | string | "/v1/reports" | The endpoint URL to submit reports to. | | appVersion | string | "1.0.0" | The version of your client application. | | environment | string | "production" | The application deployment environment (e.g. development, staging, production). | | captureErrors | boolean | true | Automatically capture unhandled runtime errors and promise rejections. | | showWidget | boolean | true | Show the beautiful floating feedback widget in the UI. | | theme | string | "dark" | Visual theme for the widget: 'dark' or 'light'. | | metadata | Object | {} | Key-value pairs to include with every report sent by the SDK. | | easterEgg | Object | — | Hidden-trigger config: { enabled, selector, clicks, timeout }. When enabled, the floating button is hidden and the panel opens after clicks clicks on selector. |

TypeScript

The package ships type declarations (src/index.d.ts) and points types/exports at them, so editors provide autocomplete and type-checking out of the box — no @types package required. Exported types include BuglineInitOptions, BuglineReport, BuglineEasterEggConfig, BuglineTheme, and BuglineSeverity:

import { Bugline, type BuglineInitOptions } from "@xtatistix/bugline-web";

const options: BuglineInitOptions = {
  apiKey: process.env.NEXT_PUBLIC_BUGLINE_API_KEY!,
  theme: "dark"
};

Bugline.init(options);

Scoped Styles Customization

The feedback widget is styled dynamically on initialization. If you need to override the styles, you can declare target CSS overrides in your main stylesheet:

:root {
  --bl-primary-color: #ef4444; /* Custom red brand color */
  --bl-primary-hover: #dc2626;
}