BugStash

Pre-production bug reporting SDK for React apps. Drop a floating debug panel into your dev/staging environment. Capture bugs with screenshots, console logs, network requests, and full browser context — then manage everything from the BugStash Dashboard.

Why BugStash?

• No more "it works on my machine" — Every bug report includes console logs, network requests, browser info, and an optional screenshot
• Zero config — One line to initialize, automatically disabled in production
• Live Pins — Click anywhere on your page to leave contextual feedback pinned to specific elements
• Built for teams — Multi-tenant dashboard with roles, projects, and real-time updates
• Privacy first — Built-in PII redaction for sensitive data

Quick Start

1. Install

npm install bugstash

2. Get your Project ID

Sign up at bugstash.vercel.app, create an organization and project, then copy your Project ID from the settings page.

3. Initialize

// app/layout.tsx or _app.tsx
import BugStash from 'bugstash';

BugStash.init({
  projectId: 'your-project-id',
  environment: 'development', // auto-disabled in 'production'
});

That's it. A floating bug button appears in the corner of your app.

Configuration

BugStash.init({
  // Required
  projectId: 'your-project-id',

  // Optional
  environment: 'development',   // 'development' | 'staging' | 'production'
  panelPosition: 'bottom-right', // 'bottom-right' | 'bottom-left'

  // Features
  enableScreenshot: true,       // Screenshot capture (default: true)
  enableAnnotation: true,       // Annotate screenshots (default: true)
  enablePerformance: true,      // Collect Web Vitals (default: true)
  enableLivePins: true,         // Pin comments on page elements (default: true)

  // Limits
  maxLogs: 100,                 // Console log buffer size
  maxNetworkCaptures: 50,       // Network request buffer size
  maxBreadcrumbs: 50,           // User action breadcrumbs

  // User context (optional)
  user: {
    id: 'user-123',
    email: '[email protected]',
    name: 'Jane Developer',
  },

  // Git commit hash (optional, shown in reports)
  commitHash: process.env.NEXT_PUBLIC_COMMIT_SHA,
});

What Gets Captured

Every bug report automatically includes:

| Category | Details | |----------|---------| | Console Logs | log, warn, error, info, debug with timestamps | | Network Requests | URL, method, status, duration, request/response size | | Errors | Uncaught exceptions and unhandled promise rejections with stack traces | | Breadcrumbs | Clicks, navigation, form submissions, custom events | | Performance | FCP, LCP, CLS, TTFB, FID (Web Vitals) | | Browser Context | User agent, viewport, URL, timestamp, OS, device | | Screenshot | Full-page capture with optional annotations |

Features

Bug Report Panel

Click the floating bug button to open the report panel. Write a description, set priority/category, attach a screenshot, and submit. All captured context is bundled automatically.

Live Pins

Pin comments directly on UI elements. Team members see pins in real-time. Great for design reviews and QA feedback.

// Toggle pin mode programmatically
BugStash.togglePinMode();
BugStash.isPinModeActive(); // boolean

Themes

Choose from built-in themes or match your app's aesthetic:

BugStash.getThemes();           // List all available themes
BugStash.setTheme('midnight');  // Switch theme
BugStash.getCurrentThemeId();   // Get current theme

Layouts

Switch between different panel layouts:

BugStash.getLayouts();          // List available layouts
BugStash.setLayout('minimal');  // Switch layout

PII Redaction

Automatically redact sensitive data before it leaves the browser:

BugStash.redactString('my email is [email protected]');
// → "my email is [EMAIL REDACTED]"

BugStash.redactObject({ password: 'secret', name: 'John' });
// → { password: '[REDACTED]', name: 'John' }

Programmatic API

Access captured data directly:

// Console logs
BugStash.getLogs();
BugStash.clearLogs();

// Network requests
BugStash.getNetworkCaptures();
BugStash.getFailedNetworkCaptures();
BugStash.clearNetworkCaptures();

// Errors
BugStash.getErrors();
BugStash.clearErrors();

// Breadcrumbs
BugStash.getBreadcrumbs();
BugStash.addBreadcrumb({ type: 'custom', message: 'User completed onboarding' });
BugStash.clearBreadcrumbs();

// Performance metrics
BugStash.getPerformanceMetrics();

// Cleanup
BugStash.destroy();

Framework Examples

Next.js (App Router)

// app/providers.tsx
'use client';

import { useEffect } from 'react';
import BugStash from 'bugstash';

export function BugStashProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    BugStash.init({
      projectId: process.env.NEXT_PUBLIC_BUGSTASH_PROJECT_ID!,
      environment: process.env.NODE_ENV as any,
    });
    return () => BugStash.destroy();
  }, []);

  return <>{children}</>;
}

// app/layout.tsx
import { BugStashProvider } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <BugStashProvider>{children}</BugStashProvider>
      </body>
    </html>
  );
}

Vite + React

// main.tsx
import BugStash from 'bugstash';

BugStash.init({
  projectId: import.meta.env.VITE_BUGSTASH_PROJECT_ID,
  environment: import.meta.env.MODE,
});

Create React App

// src/index.tsx
import BugStash from 'bugstash';

BugStash.init({
  projectId: process.env.REACT_APP_BUGSTASH_PROJECT_ID!,
  environment: process.env.NODE_ENV,
});

Dashboard

Manage all reports from the BugStash Dashboard:

• View & filter bug reports by status, priority, category, and assignee
• Assign reports to team members
• Track resolution status
• Inspect full context: logs, network, errors, screenshots
• Live Pins — see pinned comments in real-time
• Multi-tenant — multiple organizations and projects
• Team roles — owner, admin, member permissions

Sign up free at bugstash.vercel.app

How It Works

Your App (dev/staging)          BugStash Cloud
┌─────────────────────┐        ┌──────────────────┐
│                     │        │                  │
│  bugstash SDK       │───────>│  Backend API     │
│  - captures logs    │  HTTPS │  - stores reports│
│  - records network  │        │  - manages pins  │
│  - takes screenshots│        │  - real-time WS  │
│  - tracks errors    │        │                  │
│                     │        └────────┬─────────┘
└─────────────────────┘                 │
                                        v
                               ┌──────────────────┐
                               │                  │
                               │  Dashboard       │
                               │  - view reports  │
                               │  - assign bugs   │
                               │  - team collab   │
                               │                  │
                               └──────────────────┘

Production Safety

BugStash automatically disables itself when environment is set to 'production'. No data is captured, no UI is rendered, and no network requests are made. Zero overhead in production.

BugStash.init({
  projectId: 'your-project-id',
  environment: process.env.NODE_ENV, // 'production' = fully disabled
});

Requirements

• React >= 17.0.0
• Modern browser (Chrome, Firefox, Safari, Edge)
• Optional: html2canvas for screenshot capture (npm install html2canvas)

Links

• Dashboard & Sign Up
• Documentation
• GitHub

License

MIT