bugcatch-sdk

Official JavaScript/TypeScript SDK for BugCatch — lightweight error tracking for web and Node.js applications.

Features

• Automatic capture of uncaught errors and unhandled promise rejections
• Manual captureException and captureMessage APIs
• Breadcrumb trail: clicks, navigation, console calls
• User context and custom tags
• beforeSend hook to filter or modify events before sending
• Works in the browser (modern bundlers + CDN) and Node.js
• Zero runtime dependencies — ~15 KB minified

Installation

npm install bugcatch-sdk

Quick Start

import BugCatch from 'bugcatch-sdk';

BugCatch.init({
  dsn: 'https://api.bugcatch.app/ingest/<projectId>?key=<sdkKey>',
  release: '1.0.0',
  environment: 'production',
});

The DSN is available on your project page in the BugCatch dashboard.

From this point on, all uncaught errors and unhandled promise rejections are captured automatically.

Manual Captures

// Capture an Error object
try {
  await processOrder(order);
} catch (err) {
  BugCatch.captureException(err, { orderId: order.id });
}

// Capture a plain message
BugCatch.captureMessage('Quota limit reached', 'warning', { used: 95 });

User Context

// After login
BugCatch.setUser({ id: '42', email: '[email protected]', username: 'jane' });

// After logout
BugCatch.clearUser();

Tags

BugCatch.setTag('plan', 'pro');
BugCatch.setTag('region', 'eu-west-1');

Options

BugCatch.init({
  // Required
  dsn: string;

  // Optional
  release?: string;               // App version e.g. "1.2.3"
  environment?: string;           // "production" | "staging" | ...
  debug?: boolean;                // Print SDK logs to console (default: false)
  maxBreadcrumbs?: number;        // Max breadcrumbs kept in memory (default: 100)
  autoCaptureErrors?: boolean;    // Auto-attach global error handlers (default: true)
  autoCaptureBreadcrumbs?: boolean; // Auto-capture clicks, nav, console (default: true)

  // Drop errors whose message matches any of these
  ignoreErrors?: Array<string | RegExp>;

  // Drop errors originating from matching script URLs
  ignoreUrls?: Array<string | RegExp>;

  // Modify or drop an event before it is sent. Return false to discard.
  beforeSend?: (event: EventPayload) => EventPayload | false;
});

Framework Examples

React

// src/main.tsx
import BugCatch from 'bugcatch-sdk';

BugCatch.init({
  dsn: import.meta.env.VITE_BUGCATCH_DSN,
  release: import.meta.env.VITE_APP_VERSION,
  environment: import.meta.env.MODE,
});

Error boundary:

class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error) {
    BugCatch.captureException(error);
  }
  render() {
    return this.props.children;
  }
}

Vue

// src/main.ts
import BugCatch from 'bugcatch-sdk';

BugCatch.init({ dsn: import.meta.env.VITE_BUGCATCH_DSN });

app.config.errorHandler = (err) => {
  BugCatch.captureException(err);
};

Node.js / Express

import BugCatch from 'bugcatch-sdk';

BugCatch.init({
  dsn: process.env.BUGCATCH_DSN!,
  release: process.env.npm_package_version,
  environment: process.env.NODE_ENV,
  autoCaptureBreadcrumbs: false, // no DOM in Node.js
});

// Error middleware
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  BugCatch.captureException(err, { path: req.path, method: req.method });
  next(err);
});

CommonJS

const { BugCatch } = require('bugcatch-sdk');

BugCatch.init({ dsn: process.env.BUGCATCH_DSN });

Breadcrumbs

Breadcrumbs are short records of what happened before an error. The SDK captures them automatically when autoCaptureBreadcrumbs: true (default):

| Source | Category | What is recorded | |--------|----------|-----------------| | DOM clicks | ui.click | Element tag, text, id/class | | History navigation | navigation | URL navigated to | | console.warn / console.error | console | Message text |

Add breadcrumbs manually:

BugCatch.addBreadcrumb({
  timestamp: new Date().toISOString(),
  type: 'user',
  category: 'auth',
  message: 'User logged in',
  data: { method: 'google-oauth' },
});

beforeSend

Use beforeSend to scrub sensitive data or drop specific events:

BugCatch.init({
  dsn: '...',
  beforeSend(event) {
    // Drop network errors
    if (event.exception?.values?.[0]?.type === 'NetworkError') return false;

    // Scrub email from user context
    if (event.user) delete event.user.email;

    return event;
  },
});

SPA / Hot-Reload Cleanup

BugCatch.destroy(); // removes all listeners, resets singleton

License

ISC