Bug reports from inside your app, with the evidence attached.

Install and use

npm install bugbottle
npm install html-to-image   # optional, only if you want screenshots

Without npm: npm install github:mahope/bugbottle#v0.4.0, or import the built files from jsDelivr — dist/ is committed for that purpose.

1. Record console errors, then build a form (React)

import { initConsoleBuffer } from "bugbottle";
import { useBugReport } from "bugbottle/react";
import { htmlToImage } from "bugbottle/html-to-image"; // optional

initConsoleBuffer(); // once, as early as your app can manage

function ReportForm() {
  const report = useBugReport({
    endpoint: "/api/feedback",
    screenshot: htmlToImage, // leave out to disable screenshots
  });
  return (
    <form data-bugbottle onSubmit={(e) => { e.preventDefault(); void report.submit(); }}>
      {report.types.map((t) => (
        <button key={t} type="button" onClick={() => report.setType(t)}>{t}</button>
      ))}
      <textarea value={report.message} onChange={(e) => report.setMessage(e.target.value)} />
      <button type="submit" disabled={report.status === "sending"}>Send</button>
    </form>
  );
}

2. Anywhere else: three functions

import { captureScreenshot, pickElement, buildReport, sendReport } from "bugbottle";
import { htmlToImage } from "bugbottle/html-to-image";

const screenshot = await captureScreenshot(htmlToImage); // PNG data URL
const element = await pickElement();                     // null if they pressed Escape
const report = buildReport({ type: "bug", message, screenshotDataUrl: screenshot, elements: element ? [element] : [] });
const { id } = await sendReport("/api/feedback", report);

Would rather not build a form? bugbottle/ui mounts a floating button and a small dialog in a shadow root, and dist/bugbottle.js does the same from a single <script> tag with data-endpoint, data-locale and data-brand attributes.

3. Receive it on the server

import {
  decodeScreenshotDataUrl, InvalidScreenshotError, isReportType,
  normaliseConsole, normaliseContext, normaliseElements, normaliseMessage,
} from "bugbottle/server";

export async function POST(req: Request) {
  const payload = await req.json();
  const message = normaliseMessage(payload.message);
  if (!message) return Response.json({ error: "Write a message first" }, { status: 400 });
  const type = isReportType(payload.type) ? payload.type : "other";
  const context = normaliseContext(payload.context);
  const console = normaliseConsole(payload.console);
  const elements = normaliseElements(payload.elements);
  let screenshot: Uint8Array | null = null;
  try {
    if (payload.screenshotDataUrl) screenshot = decodeScreenshotDataUrl(payload.screenshotDataUrl);
  } catch (err) {
    if (!(err instanceof InvalidScreenshotError)) throw err; // a bad picture must not fail the report
  }
  const { id } = await save({ type, message, context, console, elements, screenshot });
  return Response.json({ id }, { status: 201 });
}

Works unchanged in a Next.js route handler, Hono, Cloudflare Workers, Bun, Deno or anything else built on the web Request. The helpers keep the most recent 50 console entries and verify the real PNG signature before a screenshot reaches your storage. Full API in the README.

Bundle sizes

• Core (buildReport, sendReport, console buffer)~0.8 kB gzip
• Core + element picker + React hook3.9 kB gzip
• Ready-made panel (bugbottle/ui)6.9 kB gzip
• Single script tag (dist/bugbottle.js)11.6 kB gzip