Skip to main content
The Beacon SDK captures JavaScript errors, performance metrics, and custom logs from your frontend applications.

​
Installation

npm install @kodo-status/beacon

​
Quick Start

import { Beacon } from '@kodo-status/beacon';

const beacon = new Beacon({
  key: 'bpk_your_public_key',  // Get from Dashboard > Beacon
  service: 'my-frontend',
  environment: 'production'
});

// Errors are captured automatically!

​
Configuration

const beacon = new Beacon({
  // Required
  key: 'bpk_your_public_key',

  // Recommended
  service: 'my-app',
  environment: 'production',  // 'development', 'staging', 'production'

  // Optional
  version: '1.2.3',
  debug: false,  // Enable console logging
  maxBreadcrumbs: 50,
  sampleRate: 1.0,  // 0.0 to 1.0

  // User context
  user: {
    id: 'user_123',
    email: '[email protected]',
    username: 'johndoe'
  }
});

​
Automatic Error Capture

The SDK automatically captures:
  • Unhandled exceptions - window.onerror
  • Promise rejections - unhandledrejection
  • Console errors - console.error calls
  • Network errors - Failed fetch/XHR requests

​
Manual Error Reporting

try {
  doSomethingRisky();
} catch (error) {
  beacon.captureError(error, {
    tags: { feature: 'checkout' },
    extra: { cartItems: cart.items.length }
  });
}

​
Custom Logs

beacon.log('info', 'User clicked checkout', {
  cartTotal: 99.99,
  itemCount: 3
});

beacon.log('warn', 'Payment retry', { attempt: 2 });
beacon.log('error', 'Payment failed', { reason: 'declined' });
Breadcrumbs help you understand what happened before an error: 
// Automatic breadcrumbs captured:
// - Navigation events
// - Click events
// - Console logs
// - Network requests

// Add custom breadcrumbs
beacon.addBreadcrumb({
  category: 'ui',
  message: 'User opened settings modal',
  level: 'info'
});

​
User Context

Set user information for error attribution: 
// On login
beacon.setUser({
  id: 'user_123',
  email: '[email protected]',
  username: 'johndoe'
});

// On logout
beacon.clearUser();

​
Performance Monitoring

Track page load and custom performance metrics: 
// Automatic Web Vitals tracking
// - Largest Contentful Paint (LCP)
// - First Input Delay (FID)
// - Cumulative Layout Shift (CLS)

// Custom timing
const start = performance.now();
await fetchData();
beacon.timing('api_call', performance.now() - start);

​
React Integration

import { BeaconProvider, useBeacon } from '@kodo-status/beacon/react';

function App() {
  return (
    <BeaconProvider
      config={{
        key: 'bpk_your_key',
        service: 'my-react-app'
      }}
    >
      <YourApp />
    </BeaconProvider>
  );
}

// Error boundary included automatically
// Or use the hook:
function MyComponent() {
  const beacon = useBeacon();
  beacon.log('info', 'Component rendered');
}

​
Filtering Errors

Ignore noisy or irrelevant errors: 
const beacon = new Beacon({
  key: 'bpk_...',
  beforeSend: (event) => {
    // Ignore browser extension errors
    if (event.message?.includes('chrome-extension://')) {
      return null;
    }
    // Ignore specific errors
    if (event.message === 'ResizeObserver loop limit exceeded') {
      return null;
    }
    return event;
  }
});

​
Getting Your Key

  1. Go to Dashboard > Beacon
  2. Copy your Public Key (bpk_...)
  3. Use this key in your frontend code
Never use your API key (sk_...) in frontend code. The beacon public key is safe to expose.