TraceBug Documentation
Everything you need to integrate TraceBug into your project and start generating developer-ready bug reports.
On this page
1Getting Started
TraceBug is a zero-backend bug reporting tool that works entirely in the browser. All data is stored in localStorage — no servers, no API keys, no external dependencies required.
Requirements
- ✓Any frontend framework (React, Vue, Angular, Next.js, Svelte, plain HTML)
- ✓Modern browser (Chrome, Edge, Brave, Opera recommended)
- ✓Node.js 18+ for the npm package
2SDK Setup
Install via npm
$ npm install tracebug-sdk
Initialize in your app
import TraceBug from "tracebug-sdk"; // Initialize once at app startup TraceBug.init({ projectId: "my-app", enabled: "auto", // auto | development | all | off });
Note: The enabled: "auto" option activates TraceBug only on localhost and staging environments. Use "all" to enable in production as well.
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
projectId | string | required | Identifies your application |
maxEvents | number | 200 | Max events per session |
maxSessions | number | 50 | Max sessions in localStorage |
enableDashboard | boolean | true | Show the floating bug button |
enabled | string | string[] | "auto" | auto | development | staging | all | off | hostname[] |
Configuration
TraceBug.init({
projectId: "my-app", // Required
maxEvents: 200, // Max events per session
maxSessions: 50, // Max sessions in localStorage
enableDashboard: true, // Show toolbar UI
enabled: "auto", // auto | development | staging | all | off
theme: "dark", // dark | light | auto
toolbarPosition: "right", // right | left | bottom-right | bottom-left
captureConsole: "errors", // errors | warnings | all | none
});Config is validated at runtime — invalid values fall back to defaults and log a warning. TraceBug never crashes your app due to misconfiguration.
User Identification
Identify users so sessions are attributed. Persisted in localStorage across page loads.
// Identify the current user
TraceBug.setUser({ id: "user_123", email: "dev@co.com", name: "Jane" });
// Get identified user
const user = TraceBug.getUser(); // { id, email, name } | null
// Clear user
TraceBug.clearUser();Screenshots & Annotations
Auto-download: Screenshots from the toolbar camera button auto-download as PNG files to your system.
Screenshot with annotations: Open the annotation list panel and click the green "Save" button to capture the page with annotation badges visible.
Clickable badges: Numbered badges on annotated elements are clickable — opens a popover showing intent, severity, and comment.
Chrome Extension: Uses chrome.tabs.captureVisibleTab for reliable cross-origin screenshots.
// Clean page screenshot (auto-downloads)
await TraceBug.takeScreenshot();
// Screenshot with annotation badges visible
await TraceBug.takeScreenshot({ includeAnnotations: true });3Chrome Extension Usage
The Chrome Extension lets QA testers and non-developers use TraceBug on any website without touching code. Also works in Edge, Brave, and Opera.
Install from the Chrome Web Store (link above) — works in Chrome, Edge, Brave, and Opera
Navigate to any website you want to test
Click the TraceBug extension icon in your toolbar
Click "Enable on this site" to start recording
Reproduce the bug — TraceBug captures everything automatically
Click the TraceBug toolbar to view the session and export a report
4Bug Report Format
Every bug report generated by TraceBug contains the following structured sections:
Reproduction Steps
Auto-generated numbered steps from event timeline
Console Errors
Full error messages with stack traces and source locations
Network Log
All API calls with URL, method, status code, duration
Screenshots
Captured screenshots with annotations and timestamps
Environment Info
Browser, OS, viewport, device type, connection type
Session Timeline
Color-coded event log with elapsed timestamps
Voice Notes
Tester voice descriptions converted to text
Performance Data
API response times, slowest calls, success rate
5GitHub Integration
TraceBug generates properly formatted GitHub Issue markdown. One click copies the report to clipboard, ready to paste into a new GitHub Issue.
## 🐛 Vendor Update Fails — TypeError **Environment:** Chrome 121, Windows 11, 1920x1080 **Reported:** 2026-03-12 14:23:01 ## Steps to Reproduce 1. Navigate to /vendor 2. Click "Edit" button (role=button) 3. Select "Inactive" from Status dropdown 4. Click "Update" button ## Console Errors ``` TypeError: Cannot read properties of undefined (reading 'status') at updateVendor (vendor/page.tsx:42:18) ```
Programmatic access: Call TraceBug.getGitHubIssue() to get the markdown string, or TraceBug.getJiraTicket() for Jira markup format.
Plugins & Hooks
Extend TraceBug without forking. Plugins can filter events, enrich reports, and transform exports.
// Plugin: filter or transform events
TraceBug.use({
name: "my-plugin",
onEvent: (event) => {
if (event.type === "console_log") return null; // drop
return event;
},
onReport: (report) => {
report.title = "[MyApp] " + report.title;
return report;
},
});
// Hooks: subscribe to lifecycle events
TraceBug.on("error:captured", (error) => {
console.log("Bug found:", error.data.error.message);
});
TraceBug.on("session:start", (sessionId) => {
console.log("Session started:", sessionId);
});Other methods: markAsBug() flags the session, getCompactReport() returns a Slack-friendly 2-sentence summary.
6API Reference
Recording Control
TraceBug.init(config)Initialize and start recording
TraceBug.pauseRecording()Pause event capture
TraceBug.resumeRecording()Resume event capture
TraceBug.isRecording()Returns boolean — is recording active
TraceBug.getSessionId()Returns current session ID string
Screenshots
TraceBug.takeScreenshot()Capture screenshot — returns Promise<Screenshot>
TraceBug.getScreenshots()Get all captured screenshots array
Voice Recording
TraceBug.isVoiceSupported()Check if Web Speech API is available
TraceBug.startVoiceRecording({ onUpdate, onStatus })Start speech-to-text
TraceBug.stopVoiceRecording()Stop recording — returns VoiceTranscript
TraceBug.isVoiceRecording()Returns boolean — is voice active
Reports
TraceBug.generateReport()Generate complete BugReport object
TraceBug.getGitHubIssue()Get GitHub Issue markdown string
TraceBug.getJiraTicket()Get Jira ticket markup string
TraceBug.getBugTitle()Get auto-generated bug title
TraceBug.downloadPdf()Open print dialog for PDF export
User & Session
TraceBug.setUser({ id, email, name })Identify current user (persisted in localStorage)
TraceBug.getUser()Get identified user or null
TraceBug.clearUser()Clear identified user
TraceBug.markAsBug()Flag current session as a bug
TraceBug.getCompactReport()Get 2-sentence Slack-friendly summary
Data Management
getAllSessions()Get all stored sessions array
clearAllSessions()Delete all sessions from localStorage
deleteSession(id)Delete a specific session by ID
TraceBug.destroy()Tear down TraceBug completely