@bugport.ai/widget

Install the BugPort customer-facing bug reporting widget:

npm install @bugport.ai/widget

React usage:

import { BugPortWidget } from '@bugport.ai/widget'

export function App() {
  return (
    <BugPortWidget
      projectKey='bp_pub_xxxxx'
      environment='staging'
      apiBaseUrl='http://localhost:8000/v1'
      user={{
        id: 'user_123',
        email: '[email protected]',
        name: 'QA Reviewer',
      }}
    />
  )
}

publicKey is also accepted as an alias for projectKey when you want the prop name to match the dashboard/widget-key terminology.

Imperative mounting:

import { initBugPortWidget } from '@bugport.ai/widget'

const widget = initBugPortWidget({
  projectKey: 'bp_pub_xxxxx',
  environment: 'staging',
  apiBaseUrl: 'http://localhost:8000/v1',
})

// later
widget.destroy()

window.BugPort.init(...) is also registered automatically when the package runs in a browser bundle.

A CDN/IIFE single-file build is not published yet — the package targets bundler (ESM/CJS) consumers.

Project key setup

1. In the BugPort dashboard, open your project → Widget keys.
2. Create a key for the environment you are embedding in (e.g. staging, production).
3. Copy the public key (bp_pub_…) and pass it as projectKey.

Allowed origins

Widget keys are origin-restricted. Add every site origin that will load the widget (e.g. https://app.yourcompany.com) to the key's allowed origins in the dashboard, or submissions will be rejected.

Configuration

| Prop | Type | Default | Notes | |------|------|---------|-------| | projectKey / publicKey | string | — | Public widget key (bp_pub_…). Required. | | environment | string | key default | Matches the widget key environment. | | apiBaseUrl | string | https://api.bugport.ai/v1 | Override for local/self-hosted API. | | user | { id?, email?, name?, role? } | — | Optional reporter identity. role is a staff hint (see accessibility scan below). | | projectId | string | — | BugPort project id — required only for the staff accessibility scan. | | diagnostics | BugPortDiagnosticsConfig | disabled | Optional in-page console/network capture (see below). |

Events / callbacks

| Callback | Fires when | |----------|-----------| | onSubmitted(result) | A bug was successfully submitted (result includes the dashboard URL). | | onError(error) | Submission or capture failed. | | onSubmitPayload(payload) | Before submit — inspect/augment the outgoing payload. |

Privacy / captured data

The widget captures only what the reporter triggers: feedback text, annotations, an optional screenshot, and page context (URL, viewport, user agent). Screenshots are optional. Provide a user only if you want to attribute reports.

Diagnostics (console & network capture)

Optionally attach in-page diagnostics — console logs, runtime errors, and fetch/XHR network activity — so a bug report carries the context an engineer needs. Off by default; nothing is instrumented until you opt in.

<BugPortWidget
  projectKey="bp_pub_xxxxx"
  diagnostics={{
    enabled: true,
    console: true,
    runtimeErrors: true,
    network: true,        // fetch + XHR
    requestBodies: false, // bodies are off by default (privacy)
    responseBodies: false,
    userControlled: true, // show end-user attach toggles in the report form
    deniedUrls: [/\/auth\//, 'https://api.stripe.com'],
  }}
/>

Privacy safeguards: request/response bodies are opt-in; common secrets (auth headers, tokens, password-like values) are redacted by default (redactHeaders / redactPatterns extend this); allowedUrls / deniedUrls scope what network traffic is captured; and userControlled lets the reporter decide what to attach. Buffer sizes are bounded via the max*Events options.

The collector lifecycle is managed for you — instrumentation installs on mount and is fully removed on unmount. Lower-level helpers (DiagnosticsCollector, buildDiagnosticsPayload, the redact* utilities) are also exported for advanced use.

Accessibility

WCAG picker. The report form includes a collapsed, optional "Accessibility (WCAG)" section where reporters can tag a bug with a WCAG 2.2 success criterion and conformance level. Level A and AA criteria are listed (grouped by POUR principle); AAA or future criteria can be entered via the free-text "Other criterion" option. The picked values are submitted as wcagCriterion / wcagLevel.

Staff page scan. When user.role is one of qa, qa_tester, staff, admin, owner, or internal (case-insensitive) and a projectId is configured, the panel shows a staff-only "Scan this page" action that runs an axe-core accessibility check of the live page and files the findings to BugPort. Notes:

• The role hint is a UX gate only — it is spoofable by design and is never sent to the server. The API authenticates with the widget key and enforces a rate limit of 10 scans per hour per key regardless of role.
• axe-core is not in the widget's base bundle. It is declared as a regular dependency and loaded through a dynamic import("axe-core") only when a staff user activates the scan, so your bundler emits it as a separate lazy chunk that end users never download.

Troubleshooting

• Submissions rejected (403/origin) → add your site origin to the widget key's allowed origins.
• Requests 404 → check apiBaseUrl; it must resolve to a BugPort API base ending in /v1.
• Nothing renders → ensure React 18+ is installed (peer dependency) and the component is mounted client-side.

License

MIT © BugPort. See LICENSE.