@bbearai/react

React components for integrating BugBear QA into your web application.

Installation

npm install @bbearai/react

Quick Start

1. Wrap your app with BugBearProvider

import { BugBearProvider, BugBearPanel } from '@bbearai/react';

function App() {
  return (
    <BugBearProvider
      config={{
        projectId: 'your-project-id', // Get this from BugBear dashboard
        getCurrentUser: async () => {
          // Return your logged-in user's info
          const user = await yourAuthMethod();
          if (!user) return null;
          return {
            id: user.id,
            email: user.email, // Must match email in BugBear testers list
            name: user.name,   // Optional, shown on reports
          };
        },
      }}
    >
      <YourApp />
      <BugBearPanel />
    </BugBearProvider>
  );
}

2. Add testers in BugBear dashboard

The widget only appears for users whose email is registered as a tester in your BugBear project.

Configuration Options

<BugBearProvider
  config={{
    // Required
    projectId: 'your-project-id',
    getCurrentUser: async () => ({ id: user.id, email: user.email }),

    // Optional — rich context for bug reports
    getAppContext: () => ({
      currentRoute: window.location.pathname,
      userRole: currentUser?.role,       // 'owner', 'manager', 'guest', etc.
      propertyId: currentProperty?.id,   // App-specific context
      custom: { theme: 'dark' },         // Any additional data
    }),

    // Optional — callbacks
    onNavigate: (route) => router.push(route),  // Deep linking from test cases
    onReportSubmitted: (report) => { ... },      // After report submission

    // Optional — self-hosted
    supabaseUrl: '...',
    supabaseAnonKey: '...',
  }}
  enabled={isAuthReady} // Delay init until auth is ready (default: true)
>

Why use getAppContext?

When a tester reports a bug, BugBear attaches the app context to the report. This tells the developer fixing the bug:

• Which route the bug is on (auto-captured, but getAppContext is more accurate)
• What role the user has (critical for role-dependent bugs)
• App-specific state like selected property, active filters, etc.

Without getAppContext, BugBear still captures the route automatically via window.location.pathname.

Automatic Context Capture

BugBearProvider automatically captures debugging context with zero configuration:

| Data | Details | |------|---------| | Console logs | Last 50 console.log/warn/error/info calls | | Network requests | Last 20 fetch() calls with method, URL, status, duration | | Failed response bodies | First 500 chars of 4xx/5xx response bodies | | Navigation history | Last 20 route changes (auto-tracked via pushState/popstate) | | Performance | Page load time, memory usage | | Environment | Language, timezone, online status |

This data is attached to every bug report and available to the MCP server's get_report_context tool for AI-assisted debugging.

Components

BugBearProvider

Wraps your app and provides BugBear context to child components. Automatically starts context capture.

BugBearPanel

The floating widget UI. Renders a button that opens the bug report panel.

<BugBearPanel
  position="bottom-right" // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
/>

The bug report form includes:

• Report type (Bug, Feedback, Idea)
• Severity selector (for bugs)
• Description
• "Where did it happen?" — lets the tester specify the affected route if different from current page
• Screenshot attachments

BugBearErrorBoundary

Automatically captures React errors and offers to report them.

import { BugBearErrorBoundary } from '@bbearai/react';

<BugBearErrorBoundary>
  <YourComponent />
</BugBearErrorBoundary>

Hooks

useBugBear

Access BugBear state and methods from any component.

import { useBugBear } from '@bbearai/react';

function MyComponent() {
  const {
    client,           // BugBear client instance
    isTester,         // Is current user a tester?
    isQAEnabled,      // Is QA mode enabled for this project?
    shouldShowWidget, // Should the widget be visible?
    testerInfo,       // Current tester's info
    assignments,      // Test cases assigned to this tester
    issueCounts,      // { open, done, reopened } issue counts
    refreshIssueCounts, // Refresh issue counts
    isLoading,        // Loading state
  } = useBugBear();

  // Submit a report programmatically
  const handleReport = async () => {
    await client?.submitReport({
      type: 'bug',
      description: 'Something went wrong',
      severity: 'high',
      appContext: client.getAppContext(),
    });
  };
}

Widget Screens

The widget includes screens for bug reporting, test execution, messaging, and issue tracking:

| Screen | Purpose | |--------|---------| | Home | Smart hero + action grid + issue tracking cards (Open, Done, Reopened) | | Test List | Assignments with filter tabs (All, To Do, Done, Re Opened) | | Test Detail | Step-by-step test execution | | Report | Bug/feedback submission | | Issue List | Issues filtered by category with severity indicators | | Issue Detail | Full issue details with verification proof and original bug context | | Message List | Thread list with unread badges | | Thread Detail | Chat thread with reply | | Compose Message | New message thread | | Profile | Tester info and stats |

How It Works

1. User logs in to your app
2. BugBear checks if the user's email is in the testers list
3. Context capture starts — console logs, network requests, and navigation are recorded
4. Widget appears only for registered testers when QA mode is enabled
5. Testers submit bug reports with automatic debugging context attached
6. Testers track issues — Open, Done (with verification proof), and Reopened cards on home screen
7. Reports appear in your BugBear dashboard with full context for developers

Example: Next.js App Router

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

import { BugBearProvider, BugBearPanel } from '@bbearai/react';
import { useAuth } from './auth'; // Your auth hook

export function Providers({ children }) {
  const { user, isLoaded } = useAuth();

  return (
    <BugBearProvider
      config={{
        projectId: process.env.NEXT_PUBLIC_BUGBEAR_PROJECT_ID!,
        getCurrentUser: async () => {
          if (!user) return null;
          return { id: user.id, email: user.email, name: user.name };
        },
        getAppContext: () => ({
          currentRoute: window.location.pathname,
          userRole: user?.role,
        }),
      }}
      enabled={isLoaded} // Wait for auth before initializing
    >
      {children}
      <BugBearPanel />
    </BugBearProvider>
  );
}

// next.config.ts — required for Next.js
const config = {
  transpilePackages: ['@bbearai/core', '@bbearai/react'],
};

Support

• GitHub: https://github.com/Bear-Eddy/bugbear