@toppynl/holler-capture

Embeddable capture SDK for collecting bug reports from websites.

Install

npm install @toppynl/holler-capture

bun add @toppynl/holler-capture

Quick Start

1. Create a public key

In Holler, 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 "@toppynl/holler-capture"

init({
  key: "crk_your_public_key",
  host: "https://api.holler.oftomorrow.eu",
})

If you are using Holler Cloud, host defaults to https://api.holler.oftomorrow.eu. If you are self-hosting Holler, pass your own app origin:

import { init } from "@toppynl/holler-capture"

init({
  key: "crk_your_public_key",
  host: "https://holler.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 "@toppynl/holler-capture"

init({
  key: "crk_your_public_key",
  host: "https://api.holler.oftomorrow.eu",
})

Available options:

• key: required public key from Holler Settings -> Public Keys
• host: optional Holler API origin; defaults to https://api.holler.oftomorrow.eu
• 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
• user: the identified end-user to attach to captures — { id?, email?, name? } plus any extra fields you want
• context: a freeform Record<string, unknown> attached to every capture (e.g. tenant, plan, current route)

Attaching the current user and context

Especially useful for internal tools, where knowing who reported an issue (and the app state at the time) speeds up triage. Pass user/context at init, or update them later as the user signs in/out or navigates:

import { init } from "@toppynl/holler-capture"

const capture = init({
  key: "crk_your_public_key",
  user: { id: "u_123", email: "[email protected]", name: "Ada Lovelace" },
  context: { tenant: "acme", plan: "enterprise" },
})

// later, e.g. after navigation or a login/logout
capture.setUser({ id: "u_456", email: "[email protected]" })
capture.setContext({ tenant: "acme", route: "/billing" })

// clear on logout
capture.setUser(null)

setUser / setContext replace the current value (pass null to clear). The same user and context props are accepted by CapturePlugin and stay in sync as they change.

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 "@toppynl/holler-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 "@toppynl/holler-capture"

const capturePublicKey = process.env.NEXT_PUBLIC_HOLLER_KEY

if (capturePublicKey) {
  init({
    key: capturePublicKey,
    host: process.env.NEXT_PUBLIC_HOLLER_HOST ?? "https://api.holler.oftomorrow.eu",
  })
}

Example file:

// instrumentation-client.ts
import { init } from "@toppynl/holler-capture"

const capturePublicKey = process.env.NEXT_PUBLIC_HOLLER_KEY

if (capturePublicKey) {
  init({
    key: capturePublicKey,
    host: process.env.NEXT_PUBLIC_HOLLER_HOST ?? "https://api.holler.oftomorrow.eu",
  })
}

Recommended environment variables:

NEXT_PUBLIC_HOLLER_KEY=crk_your_public_key
NEXT_PUBLIC_HOLLER_HOST=https://api.holler.oftomorrow.eu

If you are using Holler Cloud, you can omit NEXT_PUBLIC_HOLLER_HOST and just pass the public key.

React integration

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

"use client"

import { CapturePlugin } from "@toppynl/holler-capture/react"

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

With environment variables:

"use client"

import { CapturePlugin } from "@toppynl/holler-capture/react"

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

  if (!publicKey) {
    return null
  }

  return (
    <CapturePlugin
      host={process.env.NEXT_PUBLIC_HOLLER_HOST ?? "https://api.holler.oftomorrow.eu"}
      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.