bugsee-react

React bug reporting library with Bugsee backend integration. Captures screenshots, screen recordings, console logs, and network requests — submitted via a server-side proxy to avoid CORS.

⚠️ Important Notice

This library is for use with Bugsee.com only.

This project was developed by reverse engineering the Bugsee Android library (AAR) and is provided for educational purposes only. Use at your own risk. This is not an official Bugsee product and is not affiliated with or endorsed by Bugsee.

Requirements & Limitations

• Android App Required: You must create an Android app in your Bugsee dashboard. The app_token must be from an Android app, not a web or iOS app.
• Hard-coded IDs: Some internal IDs are hard-coded from the reverse-engineered Android library. This means certain features may not behave as expected in the Bugsee dashboard (e.g., event categorization, filtering, or custom views).
• No Official Support: This library may break if Bugsee changes their API. No warranty or support is provided.

By using this library, you acknowledge these limitations and agree to use it at your own risk.

Features

• Floating action button — draggable FAB, portal-rendered to document.body
• Bug report modal — title, description, severity selector, custom fields
• Screenshot capture — auto-captures the page when the report opens (WebP)
• Screen recording — background DOM recording (~5 fps rolling video)
• Console log capture — intercepts console.log/warn/error/info/debug
• Network capture — intercepts fetch and XMLHttpRequest
• Server proxy — ready-made Next.js route handler and Express middleware
• Next.js compatible — "use client" directives, SSR-safe

Installation

npm install bugsee-react

For screenshot and video capture, install the optional peer dependency:

npm install html-to-image

Quick Start

1. Client — wrap your app

import { Bugsee } from "bugsee-react";

function App() {
  return (
    <Bugsee config={{ appToken: "YOUR_BUGSEE_APP_TOKEN" }}>
      <YourApp />
    </Bugsee>
  );
}

2. Server — set up the proxy

Next.js App Router (app/api/bugsee/report/route.ts):

import { createBugseeHandler } from "bugsee-react/server";

export const POST = createBugseeHandler({
  appToken: process.env.BUGSEE_APP_TOKEN!,
});

Express:

import express from "express";
import { createBugseeMiddleware } from "bugsee-react/server";

const app = express();
app.use(express.json({ limit: "50mb" }));
app.post(
  "/api/bugsee/report",
  createBugseeMiddleware({ appToken: process.env.BUGSEE_APP_TOKEN! }),
);

Configuration

import type { BugseeConfig } from "bugsee-react";

const config: BugseeConfig = {
  appToken: "YOUR_TOKEN",
  proxyUrl: "/api/bugsee/report",       // default proxy endpoint
  defaultSeverity: "medium",
  appVersion: "1.2.3",
  labels: ["web", "production"],
  attributes: { team: "frontend" },      // custom manifest attributes
  enableScreenshot: true,                 // default: true (needs html-to-image)
  enableVideo: true,                      // default: true (needs html-to-image)
  enableNetworkCapture: true,             // default: true
  enableConsoleCapture: true,             // default: true
  floatingButtonPosition: { bottom: 24, right: 24 },
  customFields: [
    {
      key: "environment",
      label: "Environment",
      type: "select",
      required: true,
      options: ["Production", "Staging", "Development"],
    },
    { key: "browser", label: "Browser", type: "text" },
  ],
  onReportSubmitted: (report) => console.log("Submitted:", report),
  onError: (error) => console.error("Failed:", error),
};

Advanced Usage

Use individual components and the useBugsee() hook for full control:

import {
  BugseeProvider,
  BugseeFloatingButton,
  BugReportModal,
  useBugsee,
} from "bugsee-react";

function MyTrigger() {
  const { openReportModal } = useBugsee();
  return <button onClick={openReportModal}>Report Bug</button>;
}

function App() {
  return (
    <BugseeProvider config={{ appToken: "TOKEN" }}>
      <YourApp />
      <MyTrigger />
      <BugReportModal />
    </BugseeProvider>
  );
}

API Reference

Components

Component	Description
<Bugsee>	All-in-one wrapper (provider + FAB + modal)
<BugseeProvider>	Context provider only
<BugseeFloatingButton>	Draggable floating action button
<BugReportModal>	Bug report form modal

Hook — useBugsee()

Property	Type	Description
config	BugseeConfig	Current configuration
isReportModalOpen	boolean	Modal visibility state
openReportModal	() => Promise<void>	Open modal (captures screenshot + stops video)
closeReportModal	() => void	Close modal (restarts video recording)
submitReport	(report) => Promise<void>	Submit a report programmatically
isSubmitting	boolean	Submission in progress
screenshot	string | null	Base64 screenshot (WebP)
removeScreenshot	() => void	Remove the attached screenshot
hasVideo	boolean	Whether a video recording is attached
removeVideo	() => void	Remove the attached video

Server Exports (bugsee-react/server)

Export	Description
createBugseeHandler(config)	Returns a Next.js App Router POST handler
createBugseeMiddleware(config)	Returns an Express middleware function

Server config options:

import type { BugseeServerConfig } from "bugsee-react/server";

const config: BugseeServerConfig = {
  appToken: "YOUR_BUGSEE_APP_TOKEN",
  apiUrl: "https://api.bugsee.com",  // default
  appPackageId: "com.myapp",         // shown in Bugsee dashboard
  appVersion: "1.2.3",               // shown in Bugsee dashboard
};

Capture Utilities

Standalone functions if you need manual control:

import {
  startNetworkCapture, stopNetworkCapture, getNetworkEvents,
  startConsoleCapture, stopConsoleCapture, getConsoleLogs,
  ScreenRecorder,
} from "bugsee-react";

Architecture

Browser (bugsee-react)           Server (bugsee-react/server)              Bugsee
┌──────────────────────┐        ┌──────────────────────────────┐        ┌────────┐
│ FAB → Modal → JSON   │──POST──│ 1. POST /v2/sessions         │───────→│        │
│ + screenshot (b64)   │  /api/ │    → get access_token        │        │        │
│ + video (b64)        │ bugsee │ 2. Build ZIP bundle          │        │ Bugsee │
│ + logs + network     │ report │ 3. POST /v2/issues           │───────→│  API   │
│ + manifest           │        │    → get S3 upload endpoint  │        │        │
│                      │        │ 4. PUT ZIP to S3             │───────→│        │
└──────────────────────┘        └──────────────────────────────┘        └────────┘

The client posts JSON to your server proxy. The server then:

1. Creates a Bugsee session (authenticates with app_token, gets access_token)
2. Builds a ZIP bundle (manifest.json, logs.json, screenshot, video, network events)
3. Creates a Bugsee issue (sends metadata + bundle SHA256 → receives an S3 upload URL)
4. Uploads the ZIP to the S3 endpoint