bugbottle

Documentation

bugbottle documentation

One page per topic, generated from the project README, so the page you are reading and the file in the repository are the same text. This is version 0.15.0; the changelog has what moved.

Get started

Install it, record the console, and put a form in front of it.

  • InstallHeadless in-app bug reports that arrive with the evidence attached. Your UI, your endpoint, a few kilobytes.
  • Recording console errorsCall this once, from client-side code, as early as your app can manage. Anything that happens before it is not in the buffer.
  • The form (React)Call report.open() when the form appears, so the screenshot shows what they were looking at rather than the form on top of it. Anything marked…
  • The form (Vue)The same state machine, as refs. type and message are writable, so v-model works on them directly.
  • The form (Svelte)The same state machine, as a readable store: $form for the values, the methods on form for everything the reporter does.
  • The form (Solid)The same state machine, as accessors: every value is a function, so the JSX tracks exactly what it reads.
  • Catching render errors (React)When a component throws, there is no screen left to point at — but there is a message, a stack and a component stack, which is the best evidence a bug…
  • Opening it without a buttonA form nobody can find is a form nobody uses, and a floating button is not always wanted. bugbottle/triggers is two listeners, under 1.3 kB gzipped together…
  • The form (anything else)Every adapter is a thin layer over three functions that work anywhere:
  • When the network is downThe report that matters most is the one written while the application was broken — and that is exactly the one a failed fetch throws away. bugbottle/queue…
  • The ready-made panelIf you would rather not build a form, bugbottle/ui mounts a floating button and a small dialog in a shadow root, so your CSS and its CSS never meet:
  • One script tagFor a site with no build step — a WordPress theme, a static page, a client site somebody else deploys — dist/bugbottle.js is a self-contained bundle that…
  • Languages and brandingEvery string a reporter sees lives in a Locale: six status messages and the widget's ui labels. bugbottle/locales ships English, Danish, Swedish, Norwegian,…

Evidence

What a report carries besides the sentence someone typed.

  • Pointing at the elementMost reports are about one thing on the page. pickElement() turns the cursor into a crosshair, highlights whatever is under it, and resolves with a…
  • What happened beforebugbottle/breadcrumbs records the last few things the reporter did, so the report says what was happening when it broke — not only what broke. It is a…
  • What the network didBreadcrumbs say what the reporter did; bugbottle/network says what the browser did about it. "The save button does nothing" is a different report when it…
  • Performance and storageTwo questions a report almost never answers and almost always needs to: was it slow, and what state was the browser in? bugbottle/perf answers both without…
  • Replay with rrwebIf your application already records with rrweb, the half-minute before the reporter opened the panel can travel with the report. bugbottle/rrweb is an…
  • ScreenshotscaptureScreenshot takes a renderer rather than importing one. A bundler resolves every import it can see, optional or not, so a built-in import of…

Server

Receiving a report, checking it, and sending it onward.

  • Receiving a reporthandleReport is the whole endpoint. It validates every field with the helpers below, optionally scrubs, decides what happens to the screenshot, stores the…
  • RecipesThe endpoint is the same everywhere; only the sentence that produces a Request differs. Here is that sentence, once per framework, with the file path the…
  • Sending it somewhereStoring the report is one thing; seeing it is another. Eleven sinks live in bugbottle/server, ten of them a formatter over one fetch call and the eleventh a…
  • The payloadWhat arrives at your endpoint, with extra fields merged in at the top level:
  • Feeding reports to an agentA report with a selector, the element's text, the page path and the last few console errors is usually enough context for a coding agent to find the code…

Privacy

The part to read before you turn screenshots on.

  • Please read this partA screenshot of your application contains whatever the reporter could see. In a clinical system that can mean a patient photograph; in a payroll tool, a…

Reference

The exported surface, a round trip you can run, and the Action.

  • APIFrom 1.0 this list is a contract rather than a description. Semantic versioning applies to every name in it: removing or renaming an export, an option or a…
  • A working exampleexamples/vanilla-js is a complete round trip with no build step: a Node http server that receives and validates a report using bugbottle/server, and a plain…
  • GitHub ActionValidate bug reports collected by the widget inside CI — useful when your endpoint exports reports as JSON files (e.g. into a repository or artifact) and…
  • Releasingnpm run release -- patch (or minor/major) bumps the version, commits and pushes the tag. CI publishes to npm and creates the GitHub release.

About

The answers a data protection question needs, who writes this, and under which licence.

  • A privacy checklistInstalling bugbottle raises three questions before a lawyer asks them: what does it collect, where does it go, and how long is it kept. This section answers…
  • Who makes itMads Holst Jensen, a freelance web and AI developer in Denmark. bugbottle came out of client projects where "the save button does nothing" arrived by email…
  • LicenceMIT
  • Compared withWhere bugbottle sits next to Marker.io, Jam, Sentry User Feedback, BugPin and rrweb.
  • ChangelogEvery release, what it added, what it fixed and what it cost in bytes.