Documentation

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

Terminal
$ npm install tracebug-sdk

Initialize in your app

app/layout.tsx (Next.js) or index.tsx (React)
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

OptionTypeDefaultDescription
projectIdstringrequiredIdentifies your application
maxEventsnumber200Max events per session
maxSessionsnumber50Max sessions in localStorage
enableDashboardbooleantrueShow the floating bug button
enabledstring | string[]"auto"auto | development | staging | all | off | hostname[]

3Chrome Extension Usage

The Chrome Extension lets QA testers and non-developers use TraceBug on any website without touching code.

1

Open chrome://extensions/ in Chrome

2

Enable "Developer mode" in the top right

3

Click "Load unpacked" and select the tracebug-extension/ folder

4

Navigate to any website you want to test

5

Click the TraceBug extension icon in your toolbar

6

Click "Enable on this site" to start recording

7

Reproduce the bug, then click the 🐛 button that appears

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.

GitHub Issue — Auto-generated
## 🐛 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.

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

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