@arwars/simplebug-capture

Embeddable capture SDK for collecting bug reports from websites.

Install

npm install @arwars/simplebug-capture

bun add @arwars/simplebug-capture

Quick Start

1. Create a public key

In Simplebug, go to Settings -> Public Keys.

Create one public key per owned website or app surface, then add the exact origins where the widget is allowed to run, for example:

• https://example.com
• https://www.example.com
• http://localhost:3000

Copy the generated public key after saving. Public keys are safe to embed in client-side code.

2. Initialize the widget on your site

Call init() from a browser entrypoint in your app:

import { init } from "@arwars/simplebug-capture"

init({
  key: "crk_your_public_key",
  host: "https://simplebug.example.com",
})

If you are using Simplebug Cloud, host defaults to https://simplebug.example.com. If you are self-hosting Simplebug, pass your own app origin:

import { init } from "@arwars/simplebug-capture"

init({
  key: "crk_your_public_key",
  host: "https://simplebug.your-company.com",
})

That mounts the floating launcher and lets users capture a screenshot or screen recording, fill out the report form, and submit directly from your site.

Usage

init() in any browser app

Use init() when you want the smallest integration surface. Run it once in a browser-only entrypoint.

import { init } from "@arwars/simplebug-capture"

init({
  key: "crk_your_public_key",
  host: "https://simplebug.example.com",
})

Available options:

• key: required public key from Simplebug Settings -> Public Keys
• host: optional Simplebug API origin; defaults to https://simplebug.example.com
• autoMount: mount automatically on init; defaults to true
• mountTarget: custom element to mount into; defaults to document.body
• submitPath: custom bug report base path; defaults to /api/embed/bug-reports
• zIndex: custom widget stacking order

submitPath is used as the base path for the capture control-plane flow. By default the SDK derives these routes from /api/embed/bug-reports:

• /api/embed/capture-token
• /api/embed/bug-report-upload-session
• /api/embed/bug-report-finalize

The package also exports runtime controls if you need them:

import { close, init, open } from "@arwars/simplebug-capture"

init({
  key: "crk_your_public_key",
})

open()
close()

Next.js 15.3+ with instrumentation-client.ts

For Next.js 15.3 and newer, initialize the SDK once in instrumentation-client.ts so it runs globally in the browser.

import { init } from "@arwars/simplebug-capture"

const capturePublicKey = process.env.NEXT_PUBLIC_SIMPLEBUG_KEY

if (capturePublicKey) {
  init({
    key: capturePublicKey,
    host: process.env.NEXT_PUBLIC_SIMPLEBUG_HOST ?? "https://simplebug.example.com",
  })
}

Example file:

// instrumentation-client.ts
import { init } from "@arwars/simplebug-capture"

const capturePublicKey = process.env.NEXT_PUBLIC_SIMPLEBUG_KEY

if (capturePublicKey) {
  init({
    key: capturePublicKey,
    host: process.env.NEXT_PUBLIC_SIMPLEBUG_HOST ?? "https://simplebug.example.com",
  })
}

Recommended environment variables:

NEXT_PUBLIC_SIMPLEBUG_KEY=crk_your_public_key
NEXT_PUBLIC_SIMPLEBUG_HOST=https://simplebug.example.com

If you are using Simplebug Cloud, you can omit NEXT_PUBLIC_SIMPLEBUG_HOST and just pass the public key.

React integration

If you prefer a React-native integration point, use the plugin from @arwars/simplebug-capture/react and mount it once near your app root.

"use client"

import { CapturePlugin } from "@arwars/simplebug-capture/react"

export function AppProviders(): React.JSX.Element {
  return (
    <>
      <CapturePlugin
        host="https://simplebug.example.com"
        publicKey="crk_your_public_key"
      />
      {/* rest of your app */}
    </>
  )
}

With environment variables:

"use client"

import { CapturePlugin } from "@arwars/simplebug-capture/react"

export function CaptureProvider(): React.JSX.Element | null {
  const publicKey = process.env.NEXT_PUBLIC_SIMPLEBUG_KEY

  if (!publicKey) {
    return null
  }

  return (
    <CapturePlugin
      host={process.env.NEXT_PUBLIC_SIMPLEBUG_HOST ?? "https://simplebug.example.com"}
      publicKey={publicKey}
    />
  )
}

CapturePlugin accepts the same options as init(), except it uses publicKey instead of key.

Notes

• Public keys should be scoped per website or app surface.
• Allowed origins should be exact HTTP(S) origins, including local development origins you want to permit.
• The SDK must run in a browser environment.
• Browser permission prompts for screen capture are expected platform behavior.